home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / cwl2f-3.zip / FORM.DOC < prev    next >
Text File  |  1992-03-30  |  215KB  |  5,834 lines

  1. @ME.FORMAT                                                                 R    
  2.                         THE C DATA FORMS LIBRARY
  3.  
  4.               (c) Copyright P. A. McKenzie 1990, 1991, 1992
  5.                            All Rights Reserved
  6.  
  7.                               Version 1.0d
  8.  
  9.  
  10.                     T A B L E   O F   C O N T E N T S
  11.        INPUT FORMS.................................................... 1
  12.                Form Manager .......................................... 1
  13.  
  14.  
  15.        INITIALIZING THE FORM LIBRARY ................................. 2
  16.                FormInitializeSystem() ................................ 2
  17.                FormInitializeFloat() ................................. 2
  18.  
  19.  
  20.        CREATING FIELD ENTRIES IN A FORM .............................. 3
  21.        The FIELD_ENTRY structure ..................................... 3
  22.                Field Types ........................................... 4
  23.                Field Row and Column .................................. 5
  24.                Field Mask ............................................ 6
  25.                Field Fill Character .................................. 6
  26.                Field Minimum Characters............................... 6
  27.                Field Maximum Width ................................... 6
  28.                Field Options ......................................... 6
  29.                Field Starting Input Position ......................... 9
  30.                Field Attributes ...................................... 9
  31.                Field Regular Expression .............................. 9
  32.                Alternate Methods of Creating FIELD_ENTRY's ........... 10
  33.  
  34.        FormInitialize() .............................................. 13
  35.                Form Options .......................................... 13
  36.                Field Errors .......................................... 16
  37.  
  38.        Setting Number of Decimal Places in a field with
  39.        FormSetFieldDecimal() ......................................... 16
  40.  
  41.        SPECIAL DATA TYPES ............................................ 19
  42.                The LIST special field ................................ 19
  43.                     Retrieving the list selection .................... 21
  44.  
  45.                The TOGGLE special field .............................. 21
  46.                     Retrieving the toggle selection .................. 23
  47.  
  48.                The SUBFORM and VSUBFORM special fields ............... 23
  49.  
  50.                BUTTON fields ......................................... 25
  51.  
  52.                RADIO Fields and the RADIO_ENTRY structure ............ 30
  53.                     Deactivating and Activating Radio Entries......... 32
  54.                     Retrieving the Radio selection ................... 33
  55.  
  56.                CHECKBOX Fields and the CHECKBOX_ENTRY structure ...... 34
  57.                     Deactivating and Activating Checkbox Entries ..... 37
  58.                     Retrieving the checkbox selection ................ 38
  59.  
  60.        GETTING INPUT FROM A FORM ..................................... 40
  61.                FormGetInput() ........................................ 41
  62.                Virtual Form Scrolling ................................ 42
  63.                Editing Input ......................................... 42
  64.                Changing the Editing Key definitions globally using the
  65.                form_edit_key table ................................... 45
  66.  
  67.  
  68.  
  69.        Page i          The C Data Forms Library                   Page i
  70.                    T A B L E   O F   C O N T E N T S
  71.                Changing the Editing Key definitions using
  72.                FormAssignFieldKeys() ................................. 45
  73.                Traversing fields and the FORM_HIGHLIGHT option ......  47
  74.  
  75.  
  76.        ASSIGNING VALUES TO AND RETRIEVING VALUES FROM A FORM ......... 48
  77.                FormSetFieldVariable() ................................ 48
  78.                Placing input with FormPutFieldData() ................. 49
  79.                Retrieving Input with FormGetFieldData() .............. 50
  80.                Pre-filling a form with default data .................. 51
  81.                Setting up array of strings using Allocate2DArray() ... 51
  82.                Freeing a two dimensional array using Free2DArray() ... 53
  83.                Using FormInitializeFieldData() ....................... 53
  84.  
  85.  
  86.        SETTING FIELD OPTIONS ......................................... 56
  87.                FormSetFieldOptions() ................................. 56
  88.  
  89.  
  90.        SETTING FORM OPTIONS .......................................... 58
  91.                FormSetOptions() ...................................... 58
  92.  
  93.  
  94.        WRITING VALUES TO THE FIELD BUFFER ............................ 60
  95.                FormWriteFieldValue() ................................. 60
  96.  
  97.  
  98.        SETTING FIELD PRE-FUNCTIONS ................................... 61
  99.                Defining global pre-functions ......................... 61
  100.                Defining field specific pre-functions ................. 61
  101.                Return Values To The Form manager ..................... 62
  102.  
  103.  
  104.        SETTING FIELD POST-FUNCTIONS .................................. 66
  105.                Defining global post-functions ........................ 66
  106.                Defining field specific post-functions ................ 66
  107.                Return Values To The Form manager ..................... 66
  108.  
  109.  
  110.        UNDEFINED KEYSTROKE PROCESSING ................................ 69
  111.                form_undef_fkey_func and form_undef_akey_func
  112.                   function pointers .................................. 69
  113.                Specifying when to call an undefined key function is a
  114.                   Regular Expression ................................. 70
  115.                Return Values To The Form Manager ..................... 70
  116.  
  117.  
  118.        PROCESSING EDITING ERRORS ..................................... 73
  119.                Minimum Number of Characters Checking ................. 73
  120.                Overriding Error Checking for Minimum Number
  121.                  of Characters ....................................... 73
  122.                Checking if Field Characters Match Regular Expression . 74
  123.                Calling a User Written Function when errors occur ..... 75
  124.                Return Values for User Written Function ............... 75
  125.  
  126.  
  127.  
  128.  
  129.        Page ii         The C Data Forms Library                   Page ii
  130.                    T A B L E   O F   C O N T E N T S
  131.        USER DEFINED ERROR CHECKING ................................... 78
  132.                FormSetFieldValidateFunction() ........................ 78
  133.                Return Values for the user defined error function ..... 78
  134.                FormCheckFieldRange() ................................. 80
  135.  
  136.  
  137.        CLEARING A FORM ............................................... 83
  138.                FormClear() ........................................... 83
  139.  
  140.  
  141.        EXITING A FORM ................................................ 84
  142.                FormSetExitFunction() ................................. 84
  143.  
  144.  
  145.        DISPOSING OF A FORM ........................................... 88
  146.                FormFree() ............................................ 88
  147.  
  148.  
  149.        MISCELLANEOUS FORM FUNCTIONS .................................. 89
  150.                FormGetFieldString() .................................. 89
  151.                FormGetFieldRowCol() .................................. 89
  152.  
  153.  
  154.        FORM MACROS ................................................... 90
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.        Page iii        The C Data Forms Library                   Page iii
  190.  
  191.                                INPUT FORMS
  192.                                -----------
  193.  
  194.        A data entry form can be defined as a collection of input fields
  195.        that are combined in a window.  By using data entry forms, it makes
  196.        it easier to collect input.  Without data entry forms, the only way
  197.        to get input is to call a series of WindowGet...() functions.
  198.        Although this is possible, it can be very cumbersome to manage
  199.        these fields if they are not in some way logically tied together,
  200.        even though each field is independent of each other.  For example,
  201.        if you want to advance to the next field by using the down arrow
  202.        key on the keyboard, you would have to set up an undefined
  203.        keystroke function that tests for the down arrow, and then tell the
  204.        input manager to terminate the input.  You would then tell your
  205.        program to advance to the next field and start the input process
  206.        over again for the new field.
  207.  
  208.        By using forms, The C Data Forms library makes it much easier for
  209.        the programmer to set up a data entry form, without worrying about
  210.        the details of traversing from field to field, as the above example
  211.        has detailed.
  212.  
  213.        The forms in The C Data Forms Library also allow other options.
  214.        Here are a few of them:
  215.  
  216.         * You can have simple windowed forms or have forms that are larger
  217.           than the physical screen (virtual forms).
  218.  
  219.         * You have pre and post functions on the field level as well as
  220.           the global level (pre-post function is called for all fields).
  221.  
  222.         * Fields can have a user defined error function tied to them.
  223.  
  224.         * Fields can be highlighted as the input cursor is moved from
  225.           field to field, or can remain the same color regardless of where
  226.           the input cursor is.
  227.  
  228.         * Automatic conversion of a field to the right data type, and then
  229.           the converted value can be assigned to any variable you choose.
  230.  
  231.         * Choice lists, toggle fields, subforms, radio, button, and
  232.           checkbox fields are supported.
  233.  
  234.         * You can retrieve or update a field at any time, even when the
  235.           form is not the current input form.
  236.  
  237.         The above are just some of the features of The C Data Forms
  238.         Library's form functions.
  239.  
  240.  
  241.  
  242.        Form Manager
  243.        ------------
  244.  
  245.        The form manager is the set of functions internal in The C Data
  246.        Forms Library that handle the grunt work of processing a form.
  247.  
  248.  
  249.          Page 1        The C Data Forms Library               Page 1
  250.  
  251.                          INITIALIZING THE FORM LIBRARY
  252.                          -----------------------------
  253.  
  254.        This section defines the preliminaries when setting up your program
  255.        to handle forms.
  256.  
  257.        FormInitializeSystem()
  258.        ----------------------
  259.  
  260.        Before you call any form functions, you must call the
  261.        FormInitializeSystem() function.  This function sets up global
  262.        variables used by the form manager.  If this function is not
  263.        called, the form manager may act unpredictably, leading to
  264.        undesired effects.  Here is the prototype:
  265.  
  266.                 void FormInitializeSystem(void)
  267.  
  268.        There are no arguments or a return value.  This function MUST be
  269.        called after WindowInitializeSystem() to take effect.
  270.  
  271.  
  272.         #include "cwlform.h"            /* This include is needed for form
  273.                                            functions */
  274.  
  275.         main()
  276.         {
  277.           WindowInitializeSystem();
  278.           FormInitializeSystem();    /* Note how FormInitializeSystem() is
  279.                                         called after
  280.                                         WindowInitializeSystem() */
  281.         }
  282.  
  283.  
  284.        FormInitializeFloat()
  285.        ---------------------
  286.  
  287.        If you are using any floating point values in your form i.e. double
  288.        and float data types, you must call the FormInitializeFloat()
  289.        function after you call FormInitializeSystem().  This function
  290.        allows the floating point library to be loaded into your program
  291.        when the program is linked.  The C Data Forms Library will not use
  292.        any floating point functions unless FormInitializeFloat() is
  293.        called.  Here is the prototype and a small example:
  294.  
  295.        Prototype:
  296.        void FormInitializeFloat(void);
  297.  
  298.        Example:
  299.        #include "cwlform.h"
  300.        main()
  301.        {
  302.           WindowInitializeSystem();
  303.           FormInitializeSystem();
  304.           FormInitializeFloat();    /* Now C Data Forms knows to use
  305.                                         floating point routines */
  306.        }
  307.  
  308.  
  309.          Page 2        The C Data Forms Library               Page 2
  310.  
  311.                        CREATING FIELD ENTRIES IN A FORM
  312.                        --------------------------------
  313.  
  314.        The FIELD_ENTRY structure
  315.        -------------------------
  316.  
  317.        The most important thing to learn when creating a form is how to
  318.        set up the array of FIELD_ENTRY's.  These FIELD_ENTRY's define
  319.        each field of the form, the field size, location, options, regular
  320.        expression, mask, minimum visible width of the field (this allows
  321.        left and right scrolling of long fields).
  322.  
  323.        Here is the description of a FIELD_ENTRY structure:
  324.  
  325.  
  326.        int      type  --  This defines the fields data type (integer,
  327.                           double, etc.)
  328.  
  329.        unsigned row   --  This defines the row in the window (or virtual
  330.                           window) of where the field is located.
  331.  
  332.        unsigned col   --  This defines the column in the window (or
  333.                           virtual window) of where the field is located.
  334.  
  335.        char     *mask --  This is the input mask to use for the field.
  336.                           This mask is the same as the masks defined in the
  337.                           WindowGet...() family of functions.
  338.  
  339.        int      fillchar -- This is the character to use for unfilled
  340.                             input positions in the field.
  341.  
  342.        int      minchars -- This is the minimum number of characters to
  343.                             accept in a field.
  344.  
  345.        int      maxwidth -- This is the visible width of the field.  If
  346.                             the input goes beyond the right edge of
  347.                             the visible width of the field, the input
  348.                             is scrolled.
  349.  
  350.        unsigned long options -- These are the field options described for
  351.                                 the field.
  352.  
  353.        int      startpos -- This is the starting position in the field to
  354.                             place the input cursor.  Usually this is
  355.                             position 1.
  356.  
  357.        int      attr    -- Color attribute to use for the field.
  358.  
  359.        char     *regexp -- Regular expression used for the input field.
  360.  
  361.  
  362.        An array of these FIELD_ENTRY's is needed to build the form.  The
  363.        order of the array elements determine the order of processing for
  364.        each field.  Here is a simple way of creating an array of
  365.        FIELD_ENTRY's:
  366.  
  367.  
  368.  
  369.          Page 3        The C Data Forms Library               Page 3
  370.  
  371.        #include "cwlform.h"
  372.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  373.  
  374.  
  375.        FIELD_ENTRY field_array[] =
  376.  
  377.  
  378.                /* define first field entry */
  379.  
  380.                {INTEGER,   /* field type */
  381.                 1,   /* field row in window (or virtual window) */
  382.                 20,   /* field column in window (or virtual window) */
  383.                 "___",   /* field mask */
  384.                 '_',   /* fill character to use */
  385.                 1,   /* minimum characters to accept */
  386.                 3,   /* maximum field width */
  387.                 FIELD_RJUSTIFY,   /* field option to use */
  388.                 1,   /* starting position */
  389.                 NORM,   /* field attribute */
  390.                "3[0-9]",   /* regular expression to use */
  391.  
  392.                /* Now define other field entries */
  393.  
  394.        STRING, 2, 20, "__________", '_', 0, 10, NO_FIELD_OPTIONS,1,NORM,
  395.                "10.",
  396.        INTEGER,3, 20, "__", '_', 2, 2, NO_FIELD_OPTIONS, 1,NORM,
  397.               "2[0-9]",
  398.        DOUBLE,4, 20, "_______",'_',1,7, FIELD_COMMA | FIELD_LJUSTIFY,1,
  399.                NORM,"7[0-9/.]", CHAR, 5, 20, "_", '_', 1, 1,
  400.                FIELD_UPPERCASE, 1,NORM, "[YyNn]",
  401.  
  402.        /* Now terminate the field array */
  403.        FIELDEND};
  404.  
  405.        Note that "cwlform.h" includes "window.h", so there is no need to
  406.        include window.h.
  407.  
  408.        The above example creates an array of FIELD_ENTRY's called
  409.        field_array.  There are five field entries in the field_array
  410.        array.  Note that the array is terminated with a FIELDEND field
  411.        type.  The above method of initializing an array of FIELD_ENTRY's
  412.        globally is just one way to create the array of FIELD_ENTRY's.
  413.        There are other ways of creating an array of FIELD_ENTRY's by
  414.        making use of function calls.  These methods will be discussed
  415.        later.
  416.  
  417.  
  418.        Field Types
  419.        -----------
  420.  
  421.        The first member in the first entry is the constant INTEGER.  This
  422.        denotes the type of the data that will be entered in this field.
  423.        This also tells the form manager what type of conversion will be
  424.        required when converting the input.  When the user enters the
  425.        input, the input is in string form, so conversion is necessary.  A
  426.        list of the constants used here and their definitions is as
  427.        follows:
  428.  
  429.          Page 4        The C Data Forms Library               Page 4
  430.  
  431.            Integer data types:
  432.  
  433.                              C language
  434.            Constant          data type
  435.            --------          ----------
  436.            INTEGER           int
  437.            UINTEGER          unsigned int
  438.            LINTEGER          long
  439.            ULINTEGER         unsigned long
  440.            CHAR              char
  441.  
  442.  
  443.            String data types:
  444.  
  445.                              C language
  446.            Constant          data type
  447.            --------          ------------
  448.            STRING            char array[]
  449.  
  450.  
  451.  
  452.            Floating point data types:
  453.  
  454.                              C language
  455.            Constant          data type
  456.            --------          ----------
  457.            DOUBLE            double
  458.            FLOAT             float
  459.  
  460.  
  461.            Special data type:
  462.  
  463.            Constant
  464.            --------
  465.            FIELDEND
  466.            LIST
  467.            SUBFORM
  468.            VSUBFORM
  469.            TOGGLE
  470.            RADIO
  471.            CHECKBOX
  472.            BUTTON
  473.  
  474.        The special data type FIELDEND is used to terminate the array of
  475.        fields.  You MUST use this constant as the last field type, or the
  476.        form manager will not know where the last field is.  The other
  477.        special data types will be discussed later in this section.
  478.  
  479.  
  480.  
  481.        Field Row and Column
  482.        --------------------
  483.  
  484.        The second and third members of the first entry is the row and
  485.        column position number of where to place the field.  Remember that
  486.        this position can either be in a window or a virtual window.
  487.  
  488.  
  489.          Page 5        The C Data Forms Library               Page 5
  490.  
  491.        Field Mask
  492.        ----------
  493.  
  494.        The fourth member is the field mask to use for the field.  This
  495.        mask follows the same rules as input masks for the
  496.        WindowGetMask...() family of functions.  The maximum number of
  497.        characters in a mask string is 255 characters.  This includes
  498.        input and non-input positions in the mask.  If you want to
  499.        increase this number, you will have to change the constant
  500.        MAXFIELDSIZE defined in cwlform.h to whatever number you desire
  501.        plus 1 (the extra character is for the null terminator).  Then you
  502.        must recompile The C Data Forms Library using this new value.
  503.  
  504.  
  505.        Field Fill Character
  506.        --------------------
  507.  
  508.        The fifth member is the fill character to use for empty input
  509.        positions in the field.  In our example the fill character is the
  510.        underscore ('_').
  511.  
  512.  
  513.  
  514.        Field Minimum Characters
  515.        ------------------------
  516.  
  517.        The sixth member is the minimum number of characters to accept for
  518.        this field.  Our example says you must enter at least 1 character
  519.        in the first field.  You can override the field minimum by using
  520.        the FIELD_OVERRIDE_FORWARD and the FIELD_OVERRIDE_BACKWARD field
  521.        options defined below.
  522.  
  523.  
  524.  
  525.        Field Maximum Width
  526.        -------------------
  527.  
  528.        The seventh member tells us the maximum visible width of the
  529.        field.  Our example shows that the visible width should be 3
  530.        characters.
  531.  
  532.  
  533.  
  534.        Field Options
  535.        -------------
  536.  
  537.        The eighth member are the field options used on the field.  Here
  538.        are a list of the field options available:
  539.  
  540.  
  541.        FIELD_UPPERCASE - Characters entered in the field are
  542.                          automatically converted to upper case if lower
  543.                          case characters are entered.
  544.  
  545.        FIELD_LOWERCASE - Characters entered in the field are
  546.                          automatically converted to lower case if upper
  547.                          case characters are entered.
  548.  
  549.          Page 6        The C Data Forms Library               Page 6
  550.  
  551.        FIELD_ENHANCEDKEY - Field can recognize and distinguish between extra
  552.                            keys on extended keyboard (i.e.  F11, F12,
  553.                            dedicated cursor keys, etc.) and the normal
  554.                            keys.
  555.  
  556.        FIELD_CHECKREGEXP - Each character in the field will be checked
  557.                            against the field's regular expression.  This
  558.                            check is done when the user wants to accept
  559.                            the input.
  560.  
  561.        FIELD_CHECKSPACES - Spaces will be counted as valid characters
  562.                            when the form manager checks if the minimum
  563.                            number of characters has been entered.
  564.  
  565.        FIELD_AUTORETURN - The field is automatically accepted when the
  566.                           last input position is filled with a character.
  567.  
  568.        FIELD_CHECKREGEXP_IGNORECASE - Same as FIELD_CHECKREGEXP except
  569.                                       that case is ignored for
  570.                                       alphabetic characters.
  571.  
  572.        FIELD_FLUSHBUFFER - Keyboard is flushed before entering the field.
  573.                            This will override whatever the
  574.                            FLUSH_KEYBOARD() macro is set to.
  575.  
  576.        FIELD_HOMECURSOR  - Input field will be scrolled back to the first
  577.                            character when the field is accepted.  This is
  578.                            good for fields that have scrolled to the
  579.                            right.
  580.  
  581.  
  582.        FIELD_PROTECT - The input field will not be edited.  It will be
  583.                        skipped over by the form manager.
  584.  
  585.        FIELD_COMMA - This option is only used for numeric field types
  586.                      (INTEGER, UINTEGER, LONG, ULONG, DOUBLE and FLOAT
  587.                      types).  Commas are placed in the input when it is
  588.                      accepted.  While inputting in the field, the form
  589.                      manager deletes the commas.  To make sure that the
  590.                      comma formatted string will fit in the field, the
  591.                      field maximum width should be at least as long as
  592.                      the comma formatted number.
  593.  
  594.        FIELD_LJUSTIFY - The input field will be left justified when it is
  595.                         accepted.
  596.  
  597.        FIELD_RJUSTIFY - The input field will be right justified when it
  598.                         is accepted.
  599.  
  600.        FIELD_ZSUPPRESS1 - This option is used only for numeric field
  601.                           types.  The input will suppress all leading
  602.                           zeros when the field is accepted.
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.          Page 7        The C Data Forms Library               Page 7
  610.  
  611.        FIELD_ZSUPPRESS2 - This option does the same as FIELD_ZSUPPRESS1
  612.                           except that if the string entered is all zeros,
  613.                           leading zeros except for the last zero is
  614.                           suppressed.  For example, if the user enters
  615.                           "00000" the resulting string after suppressing
  616.                           will be "0".
  617.  
  618.        FIELD_PASSWORD - This is a password field.  When inputting into this
  619.                         field, only the password character (default is
  620.                         the asterisk '*') is displayed.
  621.  
  622.        FIELD_CLEARFIELD - Clears the input field if the first key pressed
  623.                           is recognized by the regular expression as a
  624.                           valid input key.  If a cursor movement key is
  625.                           pressed first, the field is not cleared if any
  626.                           subsequent input keys are pressed.
  627.  
  628.        FIELD_CHECK - When this option is chosen the field is checked to
  629.                      make sure that the minimum number of characters
  630.                      have been entered when the user wants to exit the
  631.                      form.
  632.  
  633.        FIELD_OVERRIDE_FORWARD - You can go to the next field (go toward
  634.                                 the last field) from the input field
  635.                                 without checking to see if the minimum
  636.                                 number of characters has been entered.
  637.                                 However, you cannot go to a previous
  638.                                 field (go toward the first field) if the
  639.                                 minimum number of characters is not met.
  640.  
  641.        FIELD_OVERRIDE_BACKWARD - Same as FIELD_OVERRIDE_FORWARD except
  642.                                  that you cannot go forward (toward the
  643.                                  last input field) without meeting the
  644.                                  requirements of entering the minimum
  645.                                  number of characters expected.
  646.  
  647.        NO_FIELD_OPTIONS        - The above options described are turned
  648.                                  off.
  649.  
  650.  
  651.        You can combine options with a bitwise OR (|).  For example, if
  652.        you want a numeric field zero suppressed, comma formatted, and
  653.        left justified you would do the following:
  654.  
  655.                FIELD_ZSUPPRESS1 | FIELD_COMMA | FIELD_LJUSTIFY
  656.  
  657.        If both FIELD_ZSUPPRESS1 and FIELD_ZSUPPRESS2 are used as options,
  658.        FIELD_ZSUPPRESS1 overrides FIELD_ZSUPPRESS2.
  659.  
  660.        FIELD_LJUSTIFY overrides FIELD_RJUSTIFY if both options are
  661.        chosen.
  662.  
  663.        If both FIELD_OVERRIDE_FORWARD and FIELD_OVERRIDE_BACKWARD are
  664.        chosen, you can exit a field in any direction without checking the
  665.        regular expression.
  666.  
  667.        NO_FIELD_OPTIONS must not be combined with any other options.
  668.  
  669.          Page 8        The C Data Forms Library               Page 8
  670.  
  671.        You can also turn off and turn on field options at run time and
  672.        during processing of a form by using the FormSetFieldOptions()
  673.        function defined later in the manual.
  674.  
  675.  
  676.  
  677.        Field Starting Input Position
  678.        -----------------------------
  679.  
  680.        This value tells the form manager where to place the cursor when
  681.        input is started.  The position numbers range from 1 to the
  682.        highest field position in the input field.  Usually the starting
  683.        position for the field is 1, but you can start the input anywhere
  684.        in a field.
  685.  
  686.        Field Attributes
  687.        ----------------
  688.  
  689.        The tenth member of the FIELD_ENTRY structure is the field
  690.        attribute.  This attribute will be the color of the field
  691.        characters that are inputted.  Note that in the example above, the
  692.        constants BLACK_ and WHITE_ are used instead of the usual lower
  693.        case global variables, black and white.  This is done because the
  694.        lower case color variables do not have a value until
  695.        WindowInitializeSystem() is called, while the capitalized
  696.        constants have a value that is predefined.  We need to use the
  697.        predefined constants because we are initializing an array outside
  698.        of the main() function.
  699.  
  700.  
  701.  
  702.        Field Regular Expression
  703.        ------------------------
  704.  
  705.        The last member of the FIELD_ENTRY is the regular expression to
  706.        use.  It is wise to use the proper regular expression for a given
  707.        field type.  For example, use a [0-9] type regular expression for
  708.        integer data.  Here are a list of sample regular expressions to
  709.        use for a given data type:
  710.  
  711.  
  712.                Constant               Simple Reg.
  713.                Data Type              Expression
  714.                ---------              ----------
  715.  
  716.                INTEGER or LINTEGER    [0-9], [0-9/-+]
  717.  
  718.                UINTEGER or ULINTEGER  [0-9]
  719.  
  720.                STRING                 Any regular expression.
  721.  
  722.                CHAR                   Any one character regular
  723.                                       expression.
  724.  
  725.                DOUBLE or FLOAT        [0-9], [0-9/-+], [0-9/.], [0-9/.eE]
  726.  
  727.  
  728.  
  729.          Page 9        The C Data Forms Library               Page 9
  730.  
  731.        Except for the CHAR data type, you can use multiplying factors or
  732.        complex regular expressions composed of the above regular
  733.        expressions.  The regular expressions defined above are just
  734.        examples of what you should use.
  735.  
  736.        The total length of the number of characters in the regular
  737.        expression must not exceed the maximum number of characters in a
  738.        field.  The current maximum number of characters allowed in a
  739.        field is 255.  If you want to change this, you must modify the
  740.        source code and change the constant MAXFIELDSIZE to whatever value
  741.        you choose.  Of course, you would have to recompile the source
  742.        code.
  743.  
  744.  
  745.  
  746.        Alternate Methods of Creating FIELD_ENTRY's
  747.        ------------------------------------------
  748.  
  749.        Another method of creating the FIELD_ENTRY's is to create them
  750.        dynamically.  Here is an example:
  751.  
  752.        #include "cwlform.h"
  753.        #define NUMFIELDS 5
  754.        #define NORM  CREATE_VIDEO_ATTRIBUTE(black,white)
  755.  
  756.        FIELD_ENTRY_PTR field_array;   /* Notice that we have a pointer to
  757.                                          what will be an array of
  758.                                          FIELD_ENTRY's */
  759.        main()
  760.        {
  761.          WindowInitializeSystem();
  762.          FormInitializeSystem();
  763.          FormInitializeFloat();
  764.  
  765.        /* Initialize with at least number of total fields */
  766.          field_array = FieldAllocate(NUMFIELDS);
  767.  
  768.        /* Call function to create fields in field_array sequentially */
  769.          FieldCreate(field_array,   /* FIELD_ENTRY pointer */
  770.                          1,             /* field number */
  771.  
  772.        /* The rest of the arguments are just like the first example */
  773.                        INTEGER,         /* field type */
  774.                        1,               /* field row */
  775.                        20,              /* field column */
  776.                        "___",           /* field mask */
  777.                        '_',             /* fill character */
  778.                        1,               /* minimum characters */
  779.                        3,               /* maximum field width */
  780.                        FIELD_RJUSTIFY,  /* field options */
  781.                        1,               /* starting position */
  782.                        NORM,            /* attribute */
  783.                        "3[0-9]");       /* regular expression */
  784.  
  785.          FieldCreate(field_array,2,STRING,2,20,"__________",'_',0,10,
  786.                          NO_FIELD_OPTIONS,1,NORM,"10.");
  787.  
  788.  
  789.          Page 10        The C Data Forms Library               Page 10
  790.  
  791.          FieldCreate(field_array,3,INTEGER,3,20,"__",'_',2,2,
  792.                      NO_FIELD_OPTIONS,1,NORM,"2[0-9]");
  793.  
  794.  
  795.          FieldCreate(field_array,4,DOUBLE,4,20, "_______",'_',1,7,
  796.                      FIELD_COMMA | FIELD_LJUSTIFY,1,NORM,"7[0-9/.]");
  797.  
  798.  
  799.          FieldCreate(field_array,5,CHAR,5,20,"_",'_',1,1,
  800.                      FIELD_UPPERCASE,1,NORM,"[YyNn]");
  801.  
  802.          /* Terminate fields with FieldEnd */
  803.          FieldEnd(field_array,NUMFIELDS);
  804.          /*
  805.                 some other stuff
  806.                                          */
  807.  
  808.          /* Dispose of Field entries created */
  809.          FieldDeallocate(field_array);
  810.        }
  811.  
  812.  
  813.        The difference between the above method and the method used to
  814.        globally initialize an array are the following:
  815.  
  816.        1) The variable type for field_array is FIELD_ENTRY_PTR, not
  817.        FIELD_ENTRY as the previous examples so far have illustrated.
  818.  
  819.        2) You must call the FieldAllocate() function to allocate space
  820.        for the number of fields desired.  If you do not call field
  821.        allocate, you will surely get a memory overwrite error.  The
  822.        return value to FieldAllocate() must be assigned to a
  823.        FIELD_ENTRY_PTR, as the above example shows.
  824.  
  825.        The array of fields are allocated from the heap at runtime, as
  826.        opposed to the static method which sets up the memory scheme at
  827.        link time.
  828.  
  829.        3) The next thing you must do is to fill in the field information
  830.        by calling the FieldCreate() function.  The first argument to the
  831.        FieldCreate() function is the FIELD_ENTRY_PTR.  The second
  832.        argument is the field number to assign this information to.  The
  833.        rest of the arguments are the same order as the first example i.e.
  834.        field type, row, column, mask, etc.  FieldCreate() is called for
  835.        each field desired.
  836.  
  837.        4) The FieldEnd() function must be called to terminate the list of
  838.        fields.  The first argument is the FIELD_ENTRY_PTR, and the second
  839.        argument is the total number of fields defined.
  840.  
  841.        5) After you have called FormFree() (discussed later) and no
  842.        longer need the array of fields anymore, you should call
  843.        FieldDeallocate() to free the memory assigned to the array of
  844.        fields.  The only argument to FieldDeallocate() is the
  845.        FIELD_ENTRY_PTR.
  846.  
  847.  
  848.  
  849.          Page 11        The C Data Forms Library               Page 11
  850.  
  851.        All of these functions except for FieldAllocate() have no return
  852.        values.  The FieldAllocate() function returns a FIELD_ENTRY_PTR if
  853.        successful, and a FIELD_ENTRY_NULL_PTR if unsuccessful.
  854.  
  855.        The advantages of using the above method over the first method is
  856.        that FIELD_ENTRY's are dynamically allocated rather than
  857.        statically declared at compile time.  This allows the programmer
  858.        to create loops to set up fields, read field information from a
  859.        file and assign this info to a FIELD_ENTRY, etc.
  860.  
  861.  
  862.        The disadvantages of this method is that you have to call several
  863.        functions to accomplish creating an array of fields, while the
  864.        static method does not call any functions.  Function overhead is
  865.        saved in the static method.
  866.  
  867.  
  868.        Here is another method of using statically defined data and
  869.        function calls:
  870.  
  871.        #include "cwlform.h"
  872.        #define NUMFIELDS 5
  873.        #define NORM  CREATE_VIDEO_ATTRIBUTE(black,white)
  874.  
  875.        FIELD_ENTRY field_array[NUMFIELDS+1]; /* Notice that we have an
  876.                                                 array of FIELD_ENTRY's. 1
  877.                                                 is added for FIELDEND
  878.                                                 entry */
  879.  
  880.        main()
  881.        {
  882.          WindowInitializeSystem();
  883.          FormInitializeSystem();
  884.        /* Call function to create fields in field_array sequentially */
  885.          FieldCreate(field_array,1,INTEGER,1,20,"___",'_',1,3,
  886.                      FIELD_RJUSTIFY,1,NORM,"3[0-9]");
  887.  
  888.          FieldCreate(field_array,2,STRING,2,20,"__________",'_',0,10,
  889.                      NO_FIELD_OPTIONS,1,NORM,"10.");
  890.  
  891.          FieldCreate(field_array,3,INTEGER,3,20,"__",'_',2,2,
  892.                      NO_FIELD_OPTIONS,1,NORM,"2[0-9]");
  893.  
  894.          FieldCreate(field_array,4,DOUBLE,4,20, "_______",'_',1,7,
  895.                      FIELD_COMMA | FIELD_LJUSTIFY,1,NORM,"7[0-9/.]");
  896.  
  897.          FieldCreate(field_array,5,CHAR,5,20,"_",'_',1,1,FIELD_UPPERCASE,
  898.                      1,NORM,"[YyNn]");
  899.  
  900.        /* Terminate fields with FieldEnd */
  901.          FieldEnd(field_array,NUMFIELDS);
  902.  
  903.        }
  904.  
  905.  
  906.  
  907.  
  908.  
  909.          Page 12        The C Data Forms Library               Page 12
  910.  
  911.        The above method declares an array of FIELD_ENTRY's, but does not
  912.        initialize them in the same way as the first method.  Note that
  913.        there is no function call to FieldAllocate() or FieldDeallocate()
  914.        since the array of fields, field_array, was already declared with
  915.        6 elements (NUMFIELDS + 1).  All other aspects of this method is
  916.        the same as the second method.
  917.  
  918.        This method statically declares an array but does have to allocate
  919.        any memory from the heap.
  920.  
  921.        From this point on, this manual will use the first method
  922.        discussed on page 2 when code fragments are written.
  923.  
  924.  
  925.  
  926.        FormInitialize() function
  927.        -------------------------
  928.  
  929.        The next step is to take the array of FIELD_ENTRY's and assign
  930.        them to a window.  The FormInitialize() does just this.
  931.  
  932.        A prototype of this function is as follows:
  933.  
  934.        FORMPTR FormInitialize(void *window, FIELD_ENTRY *field_entry,
  935.                               int form_options)
  936.  
  937.        Note that this function returns a pointer to a structure.  This
  938.        pointer is called a FORMPTR.  You must assign the return value to
  939.        a variable declared as a FORMPTR.
  940.  
  941.        The first argument to FormInitialize() seems strange.  The reason
  942.        for the void pointer instead of the usual WPOINTER or VWPOINTER is
  943.        that either WPOINTER or VWPOINTER can be used as the first
  944.        argument.  As was stated before, forms can either be window based
  945.        or virtual window based.
  946.  
  947.        If the first argument is a WPOINTER, the window must be
  948.        initialized and opened before calling FormInitialize().  If the
  949.        first argument is a VWPOINTER, the virtual window must be
  950.        initialized with VirtualInitialize() and must be an attributed
  951.        virtual window (VirtualInitialize() must be called with ATTRIBUTE
  952.        as the first argument).
  953.  
  954.        The second argument is the array of FIELD_ENTRY's.
  955.  
  956.        The third argument are the form options.  A list of the form
  957.        options are as follows:
  958.  
  959.  
  960.        Form Option
  961.        -----------
  962.  
  963.        FORM_WRAP    -  form manager will move the input cursor to the
  964.                        first input field if the last input field is
  965.                        accepted, and will move the input cursor to the
  966.                        last input field if the cursor goes beyond the
  967.                        first field.
  968.  
  969.          Page 13        The C Data Forms Library               Page 13
  970.  
  971.  
  972.        FORM_CHECK   -  When this option is on, all fields are checked on
  973.                        exit of the form to see if they satisfy the
  974.                        minimum number of characters.
  975.  
  976.        FORM_EXIT_INITIAL - This option allows exiting a form if an
  977.                            attempt is made to move the input cursor above
  978.                            the first input field in the form.
  979.  
  980.        FORM_NOEXIT_LAST - When this option is on, the form is not exited
  981.                           when the last field is accepted.
  982.  
  983.  
  984.        FORM_HIGHLIGHT - When this option is on, each field takes on its
  985.                        field color only when it is being inputted.  When
  986.                        a field is not being inputted, the color of the
  987.                        field is the text color of the window.
  988.  
  989.                        When this option is off, all fields take on their
  990.                        color regardless if the field is currently being
  991.                        inputted.
  992.  
  993.        FORM_VIRTUAL -  You must use this option if the first argument to
  994.                        FormInitialize() is a VWPOINTER.
  995.  
  996.        FORM_STATIC -   The form window will not be hidden when the form
  997.                        is exited.
  998.  
  999.        NO_FORM_OPTIONS  -  All options described above are turned off.
  1000.  
  1001.        You can combine form options using the bitwise OR (|).  Form
  1002.        options can be turned off or on any time using the
  1003.        FormSetOptions() function defined later in the manual.
  1004.  
  1005.        Example:
  1006.  
  1007.        #include "cwlform.h"
  1008.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  1009.  
  1010.        WPOINTER w;
  1011.        VWPOINTER vw;
  1012.  
  1013.        FORMPTR form,   /* pointers to FORM's */
  1014.                form2;
  1015.  
  1016.        FIELD_ENTRY field_array[] =
  1017.  
  1018.                {INTEGER,1,20,"___",'_',1,3,FIELD_RJUSTIFY,NORM,"3[0-9]",
  1019.                 STRING, 2, 20, "__________", '_', 0, 10,NO_FIELD_OPTIONS,
  1020.                         1,NORM, "10.",
  1021.                 INTEGER,3, 20, "__", '_', 2, 2,NO_FIELD_OPTIONS, 1,NORM,
  1022.                         "2[0-9]",
  1023.                 DOUBLE,4, 20,"_______",'_',1,7,FIELD_COMMA|FIELD_LJUSTIFY,
  1024.                         1,NORM,"7[0-9/.]",
  1025.                 CHAR, 5, 20, "_", '_', 1, 1, FIELD_UPPERCASE, 1,NORM,
  1026.                         "[YyNn]",
  1027.                 FIELDEND };
  1028.  
  1029.          Page 14        The C Data Forms Library               Page 14
  1030.  
  1031.        main()
  1032.        {
  1033.          WindowInitializeSystem();
  1034.          WindowSaveInitial(0);
  1035.          FormInitializeSystem();
  1036.          FormInitializeFloat();
  1037.          w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
  1038.          WindowOpen(w);
  1039.          /* vw must be ATTRIBUTEd if we want to use it as a form */
  1040.          vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
  1041.  
  1042.          /* Initialize with WPOINTER */
  1043.          form = FormInitialize(w,  /* window to assign form to */
  1044.                                field_array, /* array of fields */
  1045.                                NO_FORM_OPTIONS); /* form options */
  1046.  
  1047.          if (form == FORM_NULL_PTR)
  1048.          {
  1049.            printf("Form could not be initialized");
  1050.            exit(0);
  1051.          }
  1052.  
  1053.          /* Initialize with VWPOINTER */
  1054.  
  1055.          form2 = FormInitialize(vw, field_array, FORM_VIRTUAL);
  1056.          {
  1057.            printf("Form could not be initialized");
  1058.            exit(0);
  1059.          }
  1060.        }
  1061.  
  1062.        Note that when initializing with a virtual window, the option
  1063.        FORM_VIRTUAL must be used as a form option.
  1064.  
  1065.        FormInitialize() returns a valid FORMPTR if successful.  If there
  1066.        is an error, a FORM_NULL_PTR (null FORMPTR) is returned, and
  1067.        window_error_code is set to one of the following:
  1068.  
  1069.        NO_FIELDS_DEFINED if there are no fields in the FIELD_ENTRY array.
  1070.  
  1071.        NO_HEAP_MEM if there is not enough memory to allocate for the form
  1072.        and any internal field buffers.
  1073.  
  1074.        NO_INPUT_CHARS if a field mask contains no characters.
  1075.  
  1076.        INVALID_NUM_CHARS if the number of characters denoted by a field's
  1077.        regular expression does not equal the number of input positions in
  1078.        the field mask.
  1079.  
  1080.        BAD_WINDOW if the window does not exist.
  1081.  
  1082.        WINDOW_NOT_OPEN if the window is not open for writing.
  1083.  
  1084.        BAD_V_WINDOW if the virtual window specified does not exist.
  1085.  
  1086.        FIELD_RANGE_ERROR if there is a field that is out of bounds of the
  1087.                        dimensions of the window or the virtual window.
  1088.  
  1089.          Page 15        The C Data Forms Library               Page 15
  1090.  
  1091.        Field Errors
  1092.        ------------
  1093.  
  1094.        If there is an error with a particular field, the global variable
  1095.        field_bad_number tells which field is the offending field.  Field
  1096.        numbers are numbered from 1 to the highest field in the array of
  1097.        fields.
  1098.  
  1099.        Here is how a complete form error checking function routine would
  1100.        look like:
  1101.  
  1102.        #include "cwlform.h"
  1103.        #include <stdio.h>
  1104.  
  1105.        FIELD_ENTRY field_array[] = {   /* ... Initialize fields ... */ }
  1106.        VWPOINTER vw;
  1107.        WPOINTER w;
  1108.        FORMPTR form;
  1109.  
  1110.        main()
  1111.        {
  1112.          WindowInitializeSystem();
  1113.          FormInitializeSystem();
  1114.          FormInitializeFloat();
  1115.          WindowSaveInitial(0);
  1116.          w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
  1117.          WindowOpen(w);
  1118.          /* vw must be ATTRIBUTEd if we want to use it as a form */
  1119.          vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
  1120.  
  1121.          /* Initialize with WPOINTER */
  1122.          form = FormInitialize(w,  /* window to assign form to */
  1123.                                field_array, /* array of fields */
  1124.                                NO_FORM_OPTIONS); /* form options */
  1125.  
  1126.          if (form == FORM_NULL_PTR)
  1127.            write_form_error(1);
  1128.  
  1129.          /* Initialize with VWPOINTER */
  1130.          form2 = FormInitialize(vw, field_array, FORM_VIRTUAL);
  1131.          if (form2 == FORM_NULL_PTR)
  1132.            write_form_error(2);
  1133.        }
  1134.  
  1135.  
  1136.        void write_form_error(int formnum)
  1137.        {
  1138.          switch (window_error_code)
  1139.          {
  1140.            case NO_FIELDS_DEFINED:
  1141.              printf("Form %d has no fields",formnum);
  1142.            break;
  1143.  
  1144.            case NO_HEAP_MEM:
  1145.              printf("Not enough heap memory to allocate for form %d",
  1146.                      formnum);
  1147.            break;
  1148.  
  1149.          Page 16        The C Data Forms Library               Page 16
  1150.  
  1151.            case NO_INPUT_CHARS:
  1152.               printf ("Field %d has an invalid mask in form %d",
  1153.                        field_bad_number, formnum);
  1154.            break;
  1155.  
  1156.            case TOO_MANY_CHARS:
  1157.               printf("Field %d has too many input characters in form %d",
  1158.                       field_bad_number, formnum);
  1159.            break;
  1160.  
  1161.            case BAD_WINDOW:
  1162.               printf("Window or virtual window does not exist for form %d",
  1163.                       formnum);
  1164.            break;
  1165.  
  1166.            case WINDOW_NOT_OPEN:
  1167.               printf("Window not open for form %d",formnum);
  1168.            break;
  1169.  
  1170.            case BAD_V_WINDOW:
  1171.               printf("Virtual window does not exist for form %d",
  1172.                       formnum);
  1173.            break;
  1174.  
  1175.            case FIELD_RANGE_ERROR:
  1176.               printf("Field %d is out of bounds in form %d",
  1177.                       field_bad_number,formnum);
  1178.            break;
  1179.  
  1180.            default:
  1181.               printf("Undefined error for form %d",formnum);
  1182.            break;
  1183.          }
  1184.          exit(0);
  1185.        }
  1186.  
  1187.        The above function write_error_form() processes any error that may
  1188.        occur when initializing a form.
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.        Setting Number of Decimal Places in a field with
  1195.        FormSetFieldDecimal()
  1196.        ---------------------
  1197.  
  1198.        If the field type is FLOAT or DOUBLE, the form manager should be
  1199.        informed of the number of decimal places in the field.  The
  1200.        FormSetFieldDecimal() function tells the form manager the number of
  1201.        decimal places in a field.  Here is the prototype:
  1202.  
  1203.        int FormSetFieldDecimal(FORMPTR form, int entry, int numdec)
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.          Page 17        The C Data Forms Library               Page 17
  1210.  
  1211.        The first two arguments are the form and entry number,
  1212.        respectively, and the last argument is the number of decimal
  1213.        places.  If the FormSetFieldDecimal() function is not called, the
  1214.        form manager will assume 0 decimal places.  The form manager will
  1215.        round off any number that is inputted to the desired decimal
  1216.        places.
  1217.  
  1218.  
  1219.        If there are no errors, FormSetFieldDecimal() returns NO_ERROR.
  1220.  
  1221.        If there are errors, FormSetFieldDecimal() returns one of the
  1222.        following and sets window_error_code to one these values:
  1223.  
  1224.        UNDEFINED_FORM if the FORMPTR does not exist.
  1225.  
  1226.        UNDEFINED_FIELD if the field entry does not exist.
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.          Page 18        The C Data Forms Library               Page 18
  1270.  
  1271.                               SPECIAL DATA TYPES
  1272.                               ------------------
  1273.  
  1274.        In the previous section, there was a very brief discussion of the
  1275.        special data types, namely LIST, TOGGLE, SUBFORM, VSUBFORM, BUTTON,
  1276.        RADIO, and CHECKBOX.  These special data types are very useful if
  1277.        the information to be entered for a field is not a normal text
  1278.        field.  For example, LIST allows you to use a popup list of choices
  1279.        to be displayed, TOGGLE allows you to toggle between choices, and
  1280.        SUBFORM and VSUBFORM allows you to enter a subform for a field.
  1281.        The BUTTON field is a no input field, but powerful in what it can
  1282.        do.  BUTTON fields can close forms, go to previous fields, or can
  1283.        have a user defined definition if the user 'accepts' the field.
  1284.        The RADIO field implements a radio button field, and CHECKBOX
  1285.        implements a check box type field.  A discussion of radio and check
  1286.        box fields will be discussed below.
  1287.  
  1288.        For all of the special fields, the field type specified when the
  1289.        fields on the form was initialized must match with the desired
  1290.        special field for the field entry.
  1291.  
  1292.  
  1293.        The LIST special field
  1294.        ----------------------
  1295.  
  1296.        If a field type is LIST, the form manager will display a pop-up
  1297.        menu of choices.  Once the selection is made, the string in the
  1298.        pop-up menu is written to the field.  The field should be big
  1299.        enough to hold the longest string in the pop-up menu.  Where does
  1300.        the form get the pop-up menu from?  You create the pop-up menu
  1301.        just like any normal popup menu.  If you are not familiar with
  1302.        creating pop-up menus, please refer to the documentation included
  1303.        with The C Window Library.
  1304.  
  1305.        To let the form know about the pop-up menu, you must call the
  1306.        FormSetListField() function.  This function lets the form know the
  1307.        address of the pop-up menu pointer (POPUP_MENU_PTR).  Here is the
  1308.        prototype:
  1309.  
  1310.        int FormSetListField(FORMPTR form, int entry, int rank,
  1311.                             int start, POPUP_MENU_PTR pop)
  1312.  
  1313.        The first argument is the pointer to the form.  The second
  1314.        argument is the form entry to assign the POPUP_MENU_PTR to.  THe
  1315.        third argument is the rank of the popup window.  The fourth
  1316.        argument is the starting entry to place the highlight on.  Entry
  1317.        numbers are numbered from 1 to the highest entry.  The last
  1318.        argument is the POPUP_MENU_PTR itself.
  1319.  
  1320.        The form must be initialized with FormInitialize(), the entry
  1321.        number must exist and must have been defined as a LIST field, and
  1322.        the POPUP_MENU_PTR must also have been created before calling
  1323.        FormSetListField().  If any of these criteria are violated, an
  1324.        error is returned.  Here is an example:
  1325.  
  1326.        #include "cwlform.h"
  1327.        #include "menu.h"
  1328.  
  1329.          Page 19        The C Data Forms Library               Page 19
  1330.  
  1331.        FIELD_ENTRY fentry[] = {LIST,9,15,"________",' ',0,8,
  1332.                                NO_FIELD_OPTIONS,1,REVERSE,"8.",
  1333.                                FIELDEND};
  1334.        FORMPTR form;
  1335.        POPUP_MENU_ENTRY popup_entry[] = {"Choice 1",1,0,0,NULLFN,
  1336.                                        "Choice 2",2,0,0,NULLFN,
  1337.                                        "Choice 3",3,0,0,NULLFN,
  1338.                                        "Choice 4",4,0,0,NULLFN,
  1339.                                         CWL_NULL,0};
  1340.  
  1341.        POPUP_MENU_PTR popup;
  1342.        unsigned menu_colors[NUMPOPUPCOLORS];
  1343.        WPOINTER w;
  1344.        main()
  1345.        {
  1346.          int i;
  1347.          WindowInitializeSystem();
  1348.          FormInitializeSystem();
  1349.          WindowSaveInitial(0);
  1350.  
  1351.          /* set up menu colors */
  1352.          menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  1353.          menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  1354.          menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
  1355.          menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
  1356.          menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  1357.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  1358.          WindowOpen(w);
  1359.  
  1360.          /* create popup menu */
  1361.          popup = PopupCreateMenu(popup_entry,menu_colors,4,10,7,
  1362.                                  NO_POPUP_OPTIONS,WNULLFN,VWNULLFN);
  1363.  
  1364.          /* Initialize form */
  1365.          form = FormInitialize(w,fentry,FORM_HIGHLIGHT);
  1366.  
  1367.          /* Let form know about popup menu */
  1368.          FormSetListField(form,1,1,1,popup);
  1369.  
  1370.          /* get the input */
  1371.          FormGetInput(form,1,1);
  1372.        }
  1373.  
  1374.        If you take a look at the array of FIELD_ENTRY's, the first field
  1375.        type is a LIST field.  This informs the form manager that the
  1376.        first field will have a pop-up list associated with it.
  1377.  
  1378.        Also note that The POPUP_MENU_ENTRY's menu function is a NULLFN.
  1379.        The C Data Forms Library automatically assigns an internal
  1380.        function to the pop-up menu when FormSetListField() is called,
  1381.        which will supersede any function that you may have assigned to
  1382.        the menu entry.
  1383.  
  1384.        When FormSetListField() is called, the FORMPTR is assigned the
  1385.        POPUP_MENU_PTR, and any menu function is overridden by the C Data
  1386.        Forms function.
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.          Page 20        The C Data Forms Library               Page 20
  1393.  
  1394.        With a pop-up list, you can have hotkeys, secondary hotkeys,
  1395.        pre-functions, mouse support, etc. just like pop-up menus.  The
  1396.        only limit is that the function to perform when a selection is
  1397.        made is a Data Forms internal function, and not the function that
  1398.        you may have assigned to it previously.
  1399.  
  1400.        If there are no errors, FormSetListField() returns NO_ERROR.
  1401.  
  1402.        If there are errors, FormSetListField() returns one of the
  1403.        following and sets window_error_code to one these values:
  1404.  
  1405.        UNDEFINED_FORM if the FORMPTR does not exist.
  1406.  
  1407.        UNDEFINED_FIELD if the field entry does not exist.
  1408.  
  1409.        NO_HEAP_MEM if there is not enough memory to create the data
  1410.        structure required for a LIST field.
  1411.  
  1412.  
  1413.  
  1414.        Retrieving the LIST selection
  1415.        -----------------------------
  1416.  
  1417.        To inspect the choice that was selected, use the
  1418.        FormGetListChoice() function.  Here is the prototype:
  1419.  
  1420.        int FormGetListChoice(FORMPTR form, int entry)
  1421.  
  1422.        The only two arguments are the form and entry number of the LIST
  1423.        field.  If successful, FormGetListChoice() returns an integer
  1424.        denoting the LIST entry that was selected.  Entry numbers are
  1425.        numbered from 1 to the highest entry in the list, and are numbered
  1426.        in the order that was specified in the pop-up menu.
  1427.  
  1428.        If the LIST field is protected, FormGetListChoice() returns 0.
  1429.  
  1430.        If there are errors, FormGetListChoice() returns one of the
  1431.        following:
  1432.  
  1433.        UNDEFINED_FORM if the form does not exist.
  1434.  
  1435.        UNDEFINED_FIELD if the field does not exist, or the field is not a
  1436.        LIST field.
  1437.  
  1438.  
  1439.        The TOGGLE special field
  1440.        ------------------------
  1441.  
  1442.        The TOGGLE field allows you to make selections by pressing the
  1443.        space bar (default) to cycle through selections.  You can also
  1444.        accomplish the same thing with a LIST field, with a one-line
  1445.        borderless pop-up window.  However, TOGGLE fields are much easier
  1446.        to use.  To let the FORMPTR know that a field is a toggle field,
  1447.        the FIELD_ENTRY field type must have a TOGGLE type, and you must
  1448.        call the FormSetToggleField() function to assign the pointer to
  1449.        the TOGGLE list.
  1450.  
  1451.  
  1452.          Page 21        The C Data Forms Library               Page 21
  1453.  
  1454.        Here is a small example that creates a TOGGLE list:
  1455.  
  1456.        char *toglist[] = {"ITEM1", "ITEM2", "ITEM3", TOGGLE_NULL};
  1457.  
  1458.        In other words, the TOGGLE list is just an array of character
  1459.        strings, with the last character string being the TOGGLE_NULL
  1460.        constant.  You MUST have the TOGGLE_NULL constant to terminate the
  1461.        array of string, or else the form manager will not know where the
  1462.        TOGGLE list ends.  Of course this is only one of many ways to
  1463.        create and initialize an array of character strings.
  1464.  
  1465.        The prototype to the FormSetToggleField() is as follows:
  1466.  
  1467.        int FormSetToggleField(FORMPTR form, int entry, char **toglist)
  1468.  
  1469.        The first argument is the pointer to the form.  The second
  1470.        argument is the form entry to assign the toggle array to, and the
  1471.        third argument is the toggle character array.  The form must be
  1472.        initialized with FormInitialize(), the entry number must exist and
  1473.        must have been defined as a TOGGLE field.
  1474.  
  1475.        Here is an example:
  1476.  
  1477.        #include "cwlform.h"
  1478.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  1479.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  1480.  
  1481.        FIELD_ENTRY fentry[] = {TOGGLE,1,1,"________",' ',0,8,
  1482.                                NO_FIELD_OPTIONS,1,REVERSE,"8.",FIELDEND};
  1483.        FORMPTR form;
  1484.        char *tog[] = {"Choice 1","Choice 2","Choice 3","Choice 4",
  1485.                       TOGGLE_NULL};
  1486.  
  1487.        WPOINTER w;
  1488.        main()
  1489.        {
  1490.          int i;
  1491.          WindowInitializeSystem();
  1492.          FormInitializeSystem();
  1493.          WindowSaveInitial(0);
  1494.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  1495.          WindowOpen(w);
  1496.          /* Initialize form */
  1497.          form = FormInitialize(w,fentry,FORM_HIGHLIGHT|FORM_STATIC);
  1498.  
  1499.          /* Let form know about toggle field */
  1500.          FormSetToggleField(form,1,tog);
  1501.  
  1502.          /* get the input */
  1503.          FormGetInput(form,1,1);
  1504.          WindowMoveCursor(w,3,1);
  1505.  
  1506.          /* get the choice */
  1507.          WindowPrintf(w,"The choice that was made was %d",
  1508.                          FormGetToggleChoice(form,1));
  1509.        }
  1510.  
  1511.  
  1512.          Page 22        The C Data Forms Library               Page 22
  1513.  
  1514.        By default, the toggle key is the space bar, but this can be
  1515.        changed by changing the field key definitions.  This will be
  1516.        discussed later in subsequent sections.
  1517.  
  1518.        If there are no errors, FormSetToggleField() returns NO_ERROR.
  1519.  
  1520.        If there are errors, FormSetToggleField() returns one of the
  1521.        following and sets window_error_code to one these values:
  1522.  
  1523.        UNDEFINED_FORM if the FORMPTR does not exist.
  1524.  
  1525.        UNDEFINED_FIELD if the field entry does not exist.
  1526.  
  1527.  
  1528.        Retrieving the toggle selection
  1529.        -------------------------------
  1530.  
  1531.        To get the selection that was made in a toggle field, use the
  1532.        FormGetToggleChoice() function.  This function returns the toggle
  1533.        entry that was selected.  Entries are numbered from 1 to the
  1534.        highest entry in the toggle field.  Here is the prototype:
  1535.  
  1536.        int FormGetToggleChoice(FORMPTR form, int entry)
  1537.  
  1538.        The arguments are the form and entry number of the toggle field.
  1539.        FormGetToggleChoice() returns 0 if the toggle field is a protected
  1540.        field.
  1541.  
  1542.        If there are errors, FormGetToggleChoice() returns one of the
  1543.        following:
  1544.  
  1545.        UNDEFINED_FORM if the form does not exist.
  1546.  
  1547.        UNDEFINED_FIELD if the field does not exist, or the field is not a
  1548.        TOGGLE field.
  1549.  
  1550.  
  1551.  
  1552.        SUBFORM and VSUBFORM special fields
  1553.        -----------------------------------
  1554.  
  1555.        You can define a field in a form as another form.  When the field
  1556.        that is defined as a subform is entered, the form manager
  1557.        processes the subform.  When the subform is completed, the form
  1558.        manager returns control to the next field entry in the form that
  1559.        called the subform.  Subforms can contain other subforms, so there
  1560.        is no theoretical limit to the nesting level for subforms.  If you
  1561.        have deeply nested subforms, make sure that you have enough stack
  1562.        space when compiling and linking your programs.
  1563.  
  1564.        The only difference between SUBFORM and VSUBFORM is that VSUBFORM
  1565.        informs the form manager that the subform is a virtual (scrolling)
  1566.        form.
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.          Page 23        The C Data Forms Library               Page 23
  1573.  
  1574.        The way to define a field as a SUBFORM or VSUBFORM is to make sure
  1575.        the field type for the FIELD_ENTRY is SUBFORM (VSUBFORM).  Setting
  1576.        up a subform is EXACTLY the same way as you would set up a regular
  1577.        form.  THERE IS NO DIFFERENCE!  Once your subform is set up, you
  1578.        must call the FormSetSubformField() for SUBFORMS, or
  1579.        FormSetVSubformField() for VSUBFORMS.  Here are the prototypes:
  1580.  
  1581.        FormSetSubformField(FORMPTR form, int entry, int rank,
  1582.                            int start, FORMPTR subform)
  1583.  
  1584.        FormSetVSubformField(FORMPTR form, int entry, int rank,
  1585.                             int start, FORMPTR vsubform, WPOINTER viewport)
  1586.  
  1587.        The only difference between the two functions is that
  1588.        FormSetVSubformField() allows you to specify the viewport that the
  1589.        virtual form will be displayed on.  You must supply this argument
  1590.        if you want the virtual subform to work correctly.
  1591.  
  1592.        The first argument is the form to assign the subform to.  The
  1593.        second argument is the entry in the form that will be a subform
  1594.        field.  The third argument is the rank of the subform window.
  1595.        The fourth argument is the starting entry in the subform to
  1596.        begin getting input.  The fifth argument is the pointer to
  1597.        the subform itself.  The last argument in FormSetVSubformField()
  1598.        is the viewport window.  All of the above must exist, or an error
  1599.        will be returned.  Here is an example:
  1600.  
  1601.        #include "cwlform.h"
  1602.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  1603.        #define REVERSE  CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  1604.  
  1605.        /* initialize entries for form 1 */
  1606.        FIELD_ENTRY fentry[] = {INTEGER,1,1,"________",' ',0,8,
  1607.                                        NO_FIELD_OPTIONS,1,REVERSE,"8.",
  1608.                                SUBFORM,0,0,"",' ',0,0,NO_FIELD_OPTIONS,
  1609.                                        0,0,"",FIELDEND};
  1610.  
  1611.        /* initialize entries for subform */
  1612.        FIELD_ENTRY fentry2[] =
  1613.          {INTEGER,1,1,"____",' ',0,4,NO_FIELD_OPTIONS,1, REVERSE,"4.",
  1614.           FIELDEND};
  1615.  
  1616.        FORMPTR form,subform;
  1617.        WPOINTER w,w2;
  1618.  
  1619.        main()
  1620.        {
  1621.          int i;
  1622.          WindowInitializeSystem();
  1623.          FormInitializeSystem();
  1624.          WindowSaveInitial(0);
  1625.  
  1626.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  1627.          WindowOpen(w);
  1628.          w2 = WindowInitialize(BORDER,6,10,50,12,NORM,NORM,SINGLEBOX);
  1629.          WindowOpen(w2);
  1630.  
  1631.  
  1632.          Page 24        The C Data Forms Library               Page 24
  1633.  
  1634.          /* Initialize form */
  1635.          form = FormInitialize(w,fentry,FORM_HIGHLIGHT);
  1636.          subform = FormInitialize(w2,fentry2,FORM_HIGHLIGHT);
  1637.  
  1638.          /* Let form know about subform field */
  1639.          FormSetSubformField(form,2,1,1,subform);
  1640.  
  1641.          /* get the input */
  1642.          FormGetInput(form,1,1);
  1643.        }
  1644.  
  1645.        Note that a SUBFORM (VSUBFORM) FIELD_ENTRY's only important parts
  1646.        are the field type, and options.  The mask, attribute, regular
  1647.        expression, start position, row, col, etc. are irrelevant since
  1648.        the field is a whole form.  This is why the SUBFORM field entry has
  1649.        bogus (don't care) arguments for these items.
  1650.  
  1651.        If there are no errors, FormSetSubformField() and
  1652.        FormSetVSubformField() return NO_ERROR.
  1653.  
  1654.        If there are errors the return value is one of the following
  1655.  
  1656.        UNDEFINED_FORM if the FORMPTR or subform FORMPTR does not exist.
  1657.  
  1658.        UNDEFINED_FIELD if the field entry does not exist.
  1659.  
  1660.  
  1661.  
  1662.        BUTTON fields
  1663.        -------------
  1664.  
  1665.        A button field is a field that does not accept input but does
  1666.        certain actions when selected.  These actions can be anything from
  1667.        closing a form to doing a user-defined function.  When the button
  1668.        field is accepted, the action tied to the button field is done.  If
  1669.        the user wants to skip over the button field, he/she would hit a
  1670.        previous field or next field key.  These key definitions are
  1671.        discussed in the GETTING INPUT FROM A FORM section.
  1672.  
  1673.        To inform the form manager that a field is a button field, you must
  1674.        first set the field type to BUTTON.  Field types are set when
  1675.        defining the array of field entries.  After the field entries have
  1676.        been defined, the next step is to use the FormSetButtonField()
  1677.        function.  Here is the prototype to this function:
  1678.  
  1679.  
  1680.           int FormSetButtonField(FORMPTR form, int entry, int retval,
  1681.                                  char *text, int *attr,
  1682.                                  int (*button_func)(FORMPTR f, int e,
  1683.                                                     int *new_entry))
  1684.  
  1685.        The first argument is the form to set the button field.
  1686.  
  1687.        The second argument is the entry in the form to set as the button
  1688.        field.
  1689.  
  1690.  
  1691.  
  1692.          Page 25        The C Data Forms Library               Page 25
  1693.  
  1694.        The third argument is the value that will be returned to the form
  1695.        manager if the button field is accepted.  The possible return
  1696.        values and their descriptions will be discussed later.
  1697.  
  1698.        The fourth argument is a string that is written to the form window.
  1699.        This string will be placed in the (row,col) coordinates specified
  1700.        when the field was defined.  This string should contain useful
  1701.        information to the user as to what the button will do if it is
  1702.        accepted.  For example, the string "Close" can be written to the
  1703.        form window if accepting the button will close the form.  This
  1704.        string is also highlighted when the button field is the current
  1705.        field.  If the FORM_HIGHLIGHT option is on, the button field is
  1706.        only highlighted when it is the current field.
  1707.  
  1708.        The fifth argument is an array of attributes that will be used for
  1709.        highlighting the button field if it is the active field, and
  1710.        lowlighting if it is not the active field.  The positions in this
  1711.        array denote the following colors:
  1712.  
  1713.        NORMATTR - This is the color of the unhighlighted button field.
  1714.        HIATTR   - This is the color of the highlighted button.
  1715.        For instance:
  1716.  
  1717.        int myattr[2];
  1718.  
  1719.        /* ... */
  1720.        myattr[NORMATTR] = CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_);
  1721.        myattr[HIATTR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_);
  1722.  
  1723.        The last argument is a pointer to a user-defined function that will
  1724.        return a value to the form manager.  The possible return values
  1725.        will be discussed later.  The user-defined function takes three
  1726.        arguments.  The first argument is a pointer to the form that called
  1727.        your user-defined function, and the second argument is the entry in
  1728.        the form that called your user-defined function.  The third
  1729.        argument is a pointer to an integer that will denote a field number
  1730.        to change to if the FIELD_NEWFIELD value is returned to the form
  1731.        manager.  The FIELD_NEWFIELD value will be discussed below.
  1732.  
  1733.        An advantage of using a user-defined function is that the return
  1734.        value to the form manager can be dynamic.  In other words, your
  1735.        user-defined function controls what value is returned to the form
  1736.        manager.  You may have different return values that you want to
  1737.        implement depending on the state of the form, what input has been
  1738.        entered in previous fields, etc.  This user-defined function is not
  1739.        limited.  You can do just about anything in this function,
  1740.        including opening other forms, displaying windows, etc.
  1741.  
  1742.        The user-defined function MUST return a value to the form manager.
  1743.        If not, unpredictable things may happen in the processing of the
  1744.        forms.
  1745.  
  1746.        If no user-defined function is desired, use the NO_BUTTON_FUNC
  1747.        macro in place of the function pointer in the last argument in
  1748.        FormSetButtonField().  The button field will just return the
  1749.        value assigned to it if NO_BUTTON_FUNC is used.  For example:
  1750.  
  1751.  
  1752.          Page 26        The C Data Forms Library               Page 26
  1753.  
  1754.          FormSetButtonField(form,entry,FORM_EXIT,"String",NO_BUTTON_FUNC)
  1755.  
  1756.        will return FORM_EXIT if the button field is accepted.
  1757.  
  1758.        If you do have a user-defined function, the normal return value,
  1759.        i.e. the third argument in FormSetButtonField() is ignored, and the
  1760.        return value for the user-defined function is used.
  1761.  
  1762.        Here are the possible return values that a button field can return
  1763.        to the form manager.  These return values are also used for the
  1764.        user-defined function (if it exists) that is bound to the button.
  1765.  
  1766.  
  1767.        Return Value                      Definition
  1768.        ------------                      ----------
  1769.  
  1770.        FIELD_PREVFIELD            Move input cursor to the previous field
  1771.                                   in the form and start editing from there.
  1772.  
  1773.        FIELD_NEXTFIELD            Move input cursor to the next field in
  1774.                                   the form and continue editing the next
  1775.                                   field.
  1776.  
  1777.        FIELD_CONTINUE_PROCESS     Do nothing and go on to the next field.
  1778.  
  1779.        FORM_CLEAR                 Clear the form and move input cursor to
  1780.                                   first available field.
  1781.  
  1782.        FORM_ACCEPT                Accept the current input in the form and
  1783.                                   exit.
  1784.  
  1785.        FIELD_NEWFIELD             Move cursor to a new field and continue
  1786.                                   editing from there.
  1787.  
  1788.        FORM_EXIT_CLEAR            Clear the form and quit editing.
  1789.  
  1790.        FIELD_CONTINUE             Stay in the button field.
  1791.  
  1792.  
  1793.  
  1794.        The FIELD_PREVFIELD return value will move the input cursor to the
  1795.        previous field in the form.  If you try to move beyond the first
  1796.        available field on the form the FORM_WRAP and/or the
  1797.        FORM_EXIT_INITIAL form options will take action depending on
  1798.        whether they are on or off.  See CREATING FIELD ENTRIES for a
  1799.        definition of the FORM_WRAP and FORM_EXIT_INITIAL options.
  1800.  
  1801.        The FIELD_NEXTFIELD return value will move the input cursor to the
  1802.        next field in the form.  If you try to move beyond the first
  1803.        available field in the form, the FORM_WRAP form option will take
  1804.        action depending on whether this option was turned on.
  1805.  
  1806.        The FORM_CLEAR return value clears the form of all input data and
  1807.        moves the input cursor to the first available field.
  1808.  
  1809.  
  1810.  
  1811.  
  1812.          Page 27        The C Data Forms Library               Page 27
  1813.  
  1814.        The FORM_ACCEPT return value accepts all the input from the input
  1815.        fields and exits.  The form is not exited automatically if the
  1816.        FORM_CHECK option is on or if a field in the form has the
  1817.        FIELD_CHECK option on.  See CREATING FIELD ENTRIES for a definition
  1818.        of the FORM_CHECK and FIELD_CHECK options.
  1819.  
  1820.        The FORM_EXIT_CLEAR clears the form of all input and exits the
  1821.        form.  The form is not automatically cleared and exited if there is
  1822.        an exit function defined for the form.  Form exit functions are
  1823.        discussed later in the manual.
  1824.  
  1825.        The FIELD_CONTINUE_PROCESS is a 'do nothing and go on to the next
  1826.        field' return value.  Use this return value if you want the button
  1827.        function to tell the form manager to go on to the next field (or
  1828.        previous field, depending on the direction that the input cursor
  1829.        was going).  This return value is usually used if there is a
  1830.        user-defined function defined, and only the side effects that the
  1831.        user function may do is of any concern.  For instance, the
  1832.        user-defined  function may display windows, and then return.  You
  1833.        would then return a FIELD_CONTINUE_PROCESS to the form manager to
  1834.        state that you do not want anything special to be done.
  1835.  
  1836.        The FIELD_NEWFIELD return value moves the input cursor to the field
  1837.        assigned to the pointer in the third argument of the user-defined
  1838.        function.  This return value can only be used if you have a
  1839.        user-defined function that is bound to the button field.
  1840.        If you remember, the user-defined function's prototype passed a
  1841.        pointer to the current field number.  If you assign a field number
  1842.        to the dereferenced pointer and the FIELD_NEWFIELD return value is
  1843.        used, the form manager will move the input cursor to the field
  1844.        desired.  If the field entry does not exist, the form manager will
  1845.        not move the input cursor.  If the field is protected
  1846.        (FIELD_PROTECT flag is on) for the desired field, the input cursor
  1847.        is not moved.
  1848.  
  1849.        FIELD_CONTINUE returns control to the button field.  You cannot
  1850.        exit this field if it is accepted.  You can use this type of button
  1851.        field to implement help and display help information.
  1852.  
  1853.        Here is a small example of the BUTTON field:
  1854.  
  1855.        #include "cwlform.h"
  1856.        #define REVERSE  CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  1857.        #define NORM     CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  1858.        /* initialize entries for form 1 */
  1859.        FIELD_ENTRY fentry[] = {BUTTON,1,1,"",' ',0,0,
  1860.                                        NO_FIELD_OPTIONS,0,0,"",
  1861.                                BUTTON,1,10,"",
  1862.                                        ' ',0,0,NO_FIELD_OPTIONS,0,
  1863.                                            0,"", FIELDEND};
  1864.        FORMPTR form;
  1865.        WPOINTER w;
  1866.        main()
  1867.        {
  1868.  
  1869.  
  1870.  
  1871.  
  1872.          Page 28        The C Data Forms Library               Page 28
  1873.  
  1874.          int i;
  1875.          int attr[2];
  1876.          WindowInitializeSystem();
  1877.          FormInitializeSystem();
  1878.          WindowSaveInitial(0);
  1879.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  1880.          WindowOpen(w);
  1881.          attr[NORMATTR] = NORM;
  1882.          attr[HIATTR] = REVERSE;
  1883.          /* Initialize form */
  1884.          form = FormInitialize(w,fentry,FORM_HIGHLIGHT);
  1885.  
  1886.          /* Let form know about button fields */
  1887.          FormSetButtonField(form,1,FIELD_NEXTFIELD,"Accept",attr,
  1888.                              NO_BUTTON_FUNC);
  1889.          FormSetButtonField(form,2,FORM_EXIT_CLEAR,"Abort",attr,
  1890.                              NO_BUTTON_FUNC);
  1891.          WindowWriteCenterString(w,
  1892.             "Use Left or Right Arrow Keys to move highlight",3);
  1893.          /* get the input */
  1894.          FormGetInput(form,1,1);
  1895.        }
  1896.  
  1897.        In the above example, two button fields are defined.  The row and
  1898.        column entries in the field description, fentry[], tells where the
  1899.        button field will be placed.  Note that the only meaningful entries
  1900.        in the BUTTON field are its row and column in the form, and the
  1901.        field options (the only option that can be used is FIELD_PROTECT).
  1902.        All other arguments are meaningless (i.e. regular expression,
  1903.        starting input position, etc.).  The video attributes are derived
  1904.        from the array of attributes given in the FormSetButtonField()
  1905.        function.
  1906.  
  1907.        When the form encounters the first button, the highlight is moved
  1908.        to the position of the first button's prompt string.   When the
  1909.        user hits the 'accept' key, the return value FIELD_NEXTFIELD is
  1910.        returned to the form manager, informing it to move the cursor to
  1911.        the next field.  A return value of FIELD_CONTINUE_PROCESS would
  1912.        have accomplished the same thing.  The highlight is then moved to
  1913.        the next field, which is also a button field.  When the user
  1914.        accepts this field, the form is automatically exited.
  1915.  
  1916.        If there are no errors, FormSetButtonField() will return NO_ERROR.
  1917.  
  1918.        If there are errors the return value is one of the following
  1919.  
  1920.        UNDEFINED_FORM if the FORMPTR does not exist.
  1921.  
  1922.        UNDEFINED_FIELD if the field entry does not exist.
  1923.  
  1924.        NO_HEAP_MEM if there is not enough memory to allocate for the
  1925.        internal button data structure.
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.          Page 29        The C Data Forms Library               Page 29
  1933.  
  1934.        Radio Fields and the RADIO_ENTRY structure
  1935.        ------------------------------------------
  1936.  
  1937.        A radio field is a field that comprises a list of choices given to
  1938.        the user.  Only one of the choices can be chosen.  Usually a radio
  1939.        field is set up as a column and/or row of prompts with a 'floating'
  1940.        character that goes from prompt to prompt when the user is
  1941.        selecting an option.  Unlike the LIST option, the radio field is
  1942.        not a popup menu, but is comprised of text written to the form
  1943.        window.
  1944.  
  1945.        To set up a radio field, the field type must be initialized to
  1946.        RADIO.  This is done when initializing the array of field entries.
  1947.  
  1948.        The next step is to initialize an array of RADIO_ENTRY structures.
  1949.        Here is the layout for the RADIO_ENTRY structure:
  1950.  
  1951.        char *prompt         -  Prompt string to write to the form window.
  1952.  
  1953.        int hotkey_letter    -  Letter to highlight in prompt string.
  1954.  
  1955.        unsigned prompt_row  -  row to write the prompt string.
  1956.  
  1957.        unsigned prompt_col  -  column to write the prompt string.
  1958.  
  1959.        unsigned button_row  -  row to write the radio button character.
  1960.  
  1961.        unsigned button_col  -  column to write the radio button character.
  1962.  
  1963.        An array of these structures is needed to complete the total radio
  1964.        field definition.  Here is an example:
  1965.  
  1966.        RADIO_ENTRY radio_entry[] =
  1967.                        {"( ) Radio 1",'1',1,1,1,2, /* Radio Field 1 */
  1968.                         "( ) Radio 2",'2',2,1,2,2, /* Radio Field 2 */
  1969.                         "( ) Radio 3",'3',3,1,3,2, /* Radio Field 3 */
  1970.                         CWL_NULL};                 /* Terminator */
  1971.  
  1972.        Note that the variable radio_entry is an array of 3 RADIO_ENTRY's.
  1973.        The first entry is a string that will be written to the window.  In
  1974.        the example above the first RADIO_ENTRY's prompt string is
  1975.        "( ) Radio 1".  The next entry is the character to highlight in the
  1976.        prompt string.  This character will serve as a 'hotkey'.  When this
  1977.        character is pressed, the radio button character will automatically
  1978.        be placed at the desired choice.  If no hotkey is desired, this
  1979.        entry should be 0.  The third and fourth entries are the (row,col)
  1980.        coordinates of where the prompt is placed in the form window.  The
  1981.        fifth and sixth entries are the (row,col) coordinates of the
  1982.        'floating' character.  This character will be placed at the desired
  1983.        position when the user moves the highlight from entry to entry.
  1984.        Note that the above example strategically placed the floating
  1985.        character in between the parentheses in each of the prompt strings.
  1986.        This is the usual way to display a radio field, but you have the
  1987.        flexibility to design your own layouts.
  1988.  
  1989.        The array of RADIO_ENTRY's MUST be terminated with the CWL_NULL
  1990.        constant.  Leaving this out will cause unpredictable results.
  1991.  
  1992.          Page 30        The C Data Forms Library               Page 30
  1993.  
  1994.        Once the array of RADIO_ENTRY's has been set up, the next thing is
  1995.        to call the FormSetRadioField() function.  This function binds the
  1996.        RADIO_ENTRY's to the form, and defines attributes and the button
  1997.        character to use for the radio field.  Here is the prototype:
  1998.  
  1999.        int FormSetRadioField (FORMPTR form, int entry,
  2000.                               RADIO_ENTRY *rptr, int rchar,
  2001.                               int start, int *attr)
  2002.  
  2003.        The first two arguments are the form and the entry to assign the
  2004.        RADIO_ENTRY's to.  These must exist for the FormSetRadioField()
  2005.        function to succeed.  The third argument is the array of
  2006.        RADIO_ENTRY's that was set up previously.  The fourth argument is
  2007.        the character that will float from choice to choice when the user
  2008.        is deciding which selection to make.  The fifth argument is the
  2009.        starting entry to place the button character.  Entry numbers are
  2010.        numbered from 1 to the highest radio entry.  The last argument is
  2011.        an array of integers denoting the color attributes to use for the
  2012.        radio field.  Each element of this color array stands for a
  2013.        different aspect of the radio field.  Here are the constants that
  2014.        denotes positions in the color array:
  2015.  
  2016.        NORMATTR - This is the color of the unhighlighted entry.
  2017.  
  2018.        HIATTR   - This is the color of the highlighted entry.  The
  2019.                   highlighted entry is the current entry that the
  2020.                   user has the choice of accepting.  The highlight is
  2021.                   moved from entry to entry when the user hits the
  2022.                   appropriate keys.  See GETTING INPUT FROM A FORM for a
  2023.                   discussion of these keys.
  2024.  
  2025.        HOTATTR  - This is the color of the hotkey.
  2026.  
  2027.        UNAVAILATTR - This is the attribute to use for unavailable radio
  2028.                      entries.  More on available and unavailable entries
  2029.                      later on.
  2030.  
  2031.        To initialize an array that is large enough to hold the attributes,
  2032.        Use the NUMRADIOCOLORS constant.  This constant holds the number of
  2033.        colors needed to define the radio field's color scheme.
  2034.  
  2035.  
  2036.        Here is a small example of using FormSetRadioField():
  2037.  
  2038.  
  2039.        #include "cwlform.h"
  2040.        #define COLOR1 CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  2041.        #define COLOR2 CREATE_VIDEO_ATTRIBUTE(BLACK_,LIGHTWHITE_)
  2042.        #define COLOR3 COLOR2
  2043.        #define COLOR4 COLOR1
  2044.  
  2045.  
  2046.        RADIO_ENTRY radio_entry[] = {"( ) Radio 1",'1',1,1,1,2,
  2047.                                     "( ) Radio 2",'2',2,1,2,2,
  2048.                                     "( ) Radio 3",'3',3,1,3,2,
  2049.                                     CWL_NULL};
  2050.  
  2051.  
  2052.          Page 31        The C Data Forms Library               Page 31
  2053.  
  2054.        FORMPTR form;
  2055.        FIELD_ENTRY field[] = {RADIO,0,0,"",' ',NO_FIELD_OPTIONS,0,0,"",
  2056.                               FIELDEND};
  2057.  
  2058.        /* Initialize array of colors */
  2059.        int attr[NUMRADIOCOLORS];
  2060.  
  2061.        main()
  2062.        {
  2063.          int retval;
  2064.           /* Assume form is initialized */
  2065.  
  2066.          attr[NORMATTR]    = COLOR1;
  2067.          attr[HIATTR]      = COLOR2;
  2068.          attr[HOTATTR]     = COLOR3;
  2069.          attr[UNAVAILATTR] = COLOR4;
  2070.  
  2071.          retval = FormSetRadioField(form,1,radio_entry,7,1,attr);
  2072.          if (retval != NO_ERROR)
  2073.            /* some error message */
  2074.  
  2075.        }
  2076.  
  2077.        The above call to FormSetRadioField() uses the FORMPTR form and
  2078.        field entry 1 (this is the RADIO field).  The array, radio_entry,
  2079.        is used as the array of RADIO_ENTRY's.  The ASCII character 7 is
  2080.        used as the floating button character.  The IBM PC character set
  2081.        defines this as the 'bullet' character.  This character is usually
  2082.        used for radio fields, but you can use any ASCII character you
  2083.        desire (however, I highly recommend NOT using the space character!).
  2084.        The fifth argument starts the radio button character on the first
  2085.        radio entry.
  2086.  
  2087.        If there are no errors, FormSetRadioField() and will return
  2088.        NO_ERROR.
  2089.  
  2090.        If there are errors the return value is one of the following
  2091.  
  2092.        UNDEFINED_FORM if the FORMPTR does not exist.
  2093.  
  2094.        UNDEFINED_FIELD if the field entry does not exist.
  2095.  
  2096.        NO_HEAP_MEM if there is not enough memory to allocate for the
  2097.        internal radio field data structure.
  2098.  
  2099.  
  2100.  
  2101.        Deactivating and Activating Radio Entries
  2102.        -----------------------------------------
  2103.  
  2104.        If FormSetRadioField() is successful, all of the radio entries are
  2105.        available for the user to choose from.  However, there may be
  2106.        situations where you may want some options disabled.  To disable
  2107.        radio entries use the FormDeactivateRadioEntry() function.  Here is
  2108.        the prototype to the function:
  2109.  
  2110.        int FormDeactivateRadioField(FORMPTR form, int entry, int radionum)
  2111.  
  2112.          Page 32        The C Data Forms Library               Page 32
  2113.  
  2114.        The first two arguments are the form and entry number of where to
  2115.        find the radio entry.  The last argument is the entry in the radio
  2116.        field to deactivate.  The reason for using the form and entry to
  2117.        find the radio field is that you can use the same radio field in
  2118.        different forms.  Therefore you must supply the form and entry
  2119.        number to find the radio field.  Once the radio entry is found, the
  2120.        prompt string for the desired radio entry takes on the UNAVAILATTR
  2121.        color.  Also this field is skipped automatically when the user is
  2122.        moving the button character from field to field.
  2123.  
  2124.        To reactivate a field, the FormActivateRadioEntry() function is
  2125.        used.  Here is the prototype:
  2126.  
  2127.        int FormActivateRadioEntry(FORMPTR form, int entry, int radionum)
  2128.  
  2129.        The arguments have the same definition as the
  2130.        FormDeactivateRadioEntry().  The radio entry is automatically given
  2131.        its NORMATTR color.
  2132.  
  2133.  
  2134.  
  2135.        Retrieving the Radio selection
  2136.        ------------------------------
  2137.  
  2138.        To find out what selection was made in the radio field, use the
  2139.        FormGetRadioChoice() function.  This function returns the number
  2140.        of the radio entry that was chosen.  Radio entries are numbered
  2141.        from 1 to the highest entry.  Entries are numbered as they are
  2142.        ordered in the RADIO_ENTRY array.  Here is the prototype to the
  2143.        function:
  2144.  
  2145.        int FormGetRadioChoice(FORMPTR form, int entry)
  2146.  
  2147.        The only arguments are the form and field entry where the radio
  2148.        field is defined.  Here is a small example:
  2149.  
  2150.        #include "cwlform.h"
  2151.        #define COLOR1 CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  2152.        #define COLOR2 CREATE_VIDEO_ATTRIBUTE(BLACK_,LIGHTWHITE_)
  2153.        #define COLOR3 COLOR2
  2154.        #define COLOR4 COLOR1
  2155.  
  2156.        RADIO_ENTRY radio_entry[] = {"( ) Radio 1",'1',1,1,1,2,
  2157.                                     "( ) Radio 2",'2',2,1,2,2,
  2158.                                     "( ) Radio 3",'3',3,1,3,2,
  2159.                                     CWL_NULL};
  2160.        FORMPTR form;
  2161.        FIELD_ENTRY field[] = {RADIO,0,0,"",' ',0,0,NO_FIELD_OPTIONS,0,0,"",
  2162.                               FIELDEND};
  2163.  
  2164.        int attr[NUMRADIOCOLORS];
  2165.        WPOINTER w;
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.          Page 33        The C Data Forms Library               Page 33
  2173.  
  2174.        main()
  2175.        {
  2176.          WindowInitializeSystem();
  2177.          FormInitializeSystem();
  2178.          WindowSaveInitial(0);
  2179.  
  2180.          w = WindowInitialize(BORDER,1,1,78,22,COLOR1,COLOR1,SINGLEBOX);
  2181.          WindowOpen(w);
  2182.  
  2183.          /* Initialize form */
  2184.          form = FormInitialize(w,field,FORM_HIGHLIGHT|FORM_STATIC);
  2185.  
  2186.          attr[NORMATTR]    = COLOR1;
  2187.          attr[HIATTR]      = COLOR2;
  2188.          attr[HOTATTR]     = COLOR3;
  2189.          attr[UNAVAILATTR] = COLOR4;
  2190.  
  2191.          FormSetRadioField(form,1,radio_entry,7,1,attr);
  2192.          WindowWriteCenterString(w,
  2193.             "Hit TAB to accept, Up or Down Arrows to change choice",4);
  2194.          FormGetInput(form,1,1);
  2195.          WindowMoveCursor(w,5,20);
  2196.          VideoPrintf("The radio choice was %d",FormGetRadioChoice(form,1));
  2197.        }
  2198.  
  2199.  
  2200.        The example above sets up a radio field, gets the input from the
  2201.        form, and then prints the radio entry that was chosen.  You can
  2202.        call the FormGetRadioChoice() at any time, even in user-defined
  2203.        functions that may be performed while the form is active.
  2204.  
  2205.        If successful, FormGetRadioChoice() returns the current radio entry
  2206.        that is chosen.  If all of the radio entries are deactivated, or
  2207.        the radio field is a protected field (no input will be accepted),
  2208.        the return value is 0.
  2209.  
  2210.        If there are errors the return value is one of the following
  2211.  
  2212.        UNDEFINED_FORM if the FORMPTR does not exist.
  2213.  
  2214.        UNDEFINED_FIELD if the field entry does not exist.
  2215.  
  2216.  
  2217.  
  2218.  
  2219.        Checkbox Fields and the CHECKBOX_ENTRY structure
  2220.        ------------------------------------------------
  2221.  
  2222.        A checkbox field is a field that comprises a list of choices given
  2223.        to the user.  Any number of these choices can be selected.  This
  2224.        differs from the radio field defined above in that the radio
  2225.        fields only allowed one selection.
  2226.  
  2227.        To set up a checkbox field, the field type must be initialized to
  2228.        CHECKBOX.  This is done when initializing the array of field
  2229.        entries.
  2230.  
  2231.  
  2232.          Page 34        The C Data Forms Library               Page 34
  2233.  
  2234.        The next step is to initialize an array of CHECKBOX_ENTRY
  2235.        structures.  Here is the layout for the CHECKBOX_ENTRY structure:
  2236.  
  2237.        char *prompt         -  Prompt string to write to the form window.
  2238.  
  2239.        int hotkey_letter    -  Letter to highlight in prompt string.
  2240.  
  2241.        unsigned prompt_row  -  row to write the prompt string.
  2242.  
  2243.        unsigned prompt_col  -  column to write the prompt string.
  2244.  
  2245.        unsigned button_row  -  row to write the checkbox button character.
  2246.  
  2247.        unsigned button_col  -  column to write the checkbox button
  2248.                                character.
  2249.  
  2250.  
  2251.        An array of these structures is needed to complete the total
  2252.        checkbox field definition.  Here is an example:
  2253.  
  2254.        CHECKBOX_ENTRY checkbox_entry[] =
  2255.                {"[ ] Check 1",'1',1,1,1,2,  /* Checkbox field 1 */
  2256.                 "[ ] Check 2",'2',2,1,2,2,  /* Checkbox field 2 */
  2257.                 "[ ] Check 3",'3',3,1,3,2,  /* Checkbox field 3 */
  2258.                  CWL_NULL};                 /* Terminator */
  2259.  
  2260.        Note that the variable checkbox_entry is an array of 3
  2261.        CHECKBOX_ENTRY's.  The first entry is a string that will be written
  2262.        to the window.  In the example above the first CHECKBOX_ENTRY's
  2263.        prompt string is "[ ] Check 1".  The next entry is the character to
  2264.        highlight in the prompt string.  This character will serve as a
  2265.        'hotkey'.  When this character is pressed, the checkbox button
  2266.        character will automatically be placed at the desired choice.  If
  2267.        no hotkey is desired, this entry should be 0.  The third and fourth
  2268.        entries are the (row,col) coordinates of where the prompt is placed
  2269.        in the form window.  The fifth and sixth entries are the (row,col)
  2270.        coordinates of the checkbox character.  This character will be
  2271.        placed at the desired position when the choice is selected.  Note
  2272.        that the above example strategically placed the checkbox character
  2273.        in between the brackets in each of the prompt strings.  This is
  2274.        the usual way to display a checkbox field, but you have the
  2275.        flexibility to design your own layouts.
  2276.  
  2277.        The array of CHECKBOX_ENTRY's MUST be terminated with the CWL_NULL
  2278.        constant.  Leaving this out will cause unpredictable results.
  2279.  
  2280.        Once the array of CHECKBOX_ENTRY's has been set up, the next thing
  2281.        is to call the FormSetCheckboxField() function.  This function
  2282.        binds the CHECKBOX_ENTRY's to the form, and defines attributes and
  2283.        the button character to use for the checkbox field.  Here is the
  2284.        prototype:
  2285.  
  2286.        int FormSetCheckboxField (FORMPTR form, int entry,
  2287.                               CHECKBOX_ENTRY cptr[], int cchar,
  2288.                               int start, int *attr)
  2289.  
  2290.  
  2291.  
  2292.          Page 35        The C Data Forms Library               Page 35
  2293.  
  2294.        The first two arguments are the form and the entry to assign the
  2295.        CHECKBOX_ENTRY's to.  These must exist for the FormSetCheckbox()
  2296.        function to succeed.  The third argument is the array of
  2297.        CHECKBOX_ENTRY's that was set up previously.  The fourth argument
  2298.        is the character that will be placed in when the entry is selected.
  2299.        The fifth argument is the checkbox entry to place the cursor when
  2300.        the field is initially edited.   The last argument is an array of
  2301.        integers denoting the color attribute to use for the checkbox
  2302.        field.  Each element of this color array stands for a different
  2303.        aspect of the checkbox field.  Here are the constants that denotes
  2304.        positions in the color array:
  2305.  
  2306.        NORMATTR - This is the color of the unhighlighted entry.
  2307.  
  2308.        HIATTR   - This is the color of the highlighted entry.  The
  2309.                   highlighted entry is the current entry that the
  2310.                   user has the choice of accepting.  The highlight is
  2311.                   moved from entry to entry when the user hits the
  2312.                   appropriate keys.  See GETTING INPUT FROM A FORM for a
  2313.                   discussion of these keys.
  2314.  
  2315.        HOTATTR  - This is the color of the hotkey.
  2316.  
  2317.        UNAVAILATTR - This is the attribute to use for unavailable checkbox
  2318.                      entries.  More on available and unavailable entries
  2319.                      later on.
  2320.  
  2321.        To initialize an array that is large enough to hold the attributes,
  2322.        Use the NUMCHECKBOXCOLORS constant.  This constant holds the number of
  2323.        colors needed to define the checkbox field's color scheme.
  2324.  
  2325.        Here is a small example of using FormSetCheckboxField():
  2326.  
  2327.        #include "cwlform.h"
  2328.        #define COLOR1 CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  2329.        #define COLOR2 CREATE_VIDEO_ATTRIBUTE(BLACK_,LIGHTWHITE_)
  2330.        #define COLOR3 COLOR2
  2331.        #define COLOR4 COLOR1
  2332.  
  2333.        CHECKBOX_ENTRY checkbox_entry[] = {"[ ] Check 1",'1',1,1,1,2,
  2334.                                           "[ ] Check 2",'2',2,1,2,2,
  2335.                                           "[ ] Check 3",'3',3,1,3,2,
  2336.                                           CWL_NULL};
  2337.  
  2338.        FORMPTR form;
  2339.        FIELD_ENTRY field[] = {CHECKBOX,0,0,"",' ',0,0,NO_FIELD_OPTIONS,
  2340.                               "", FIELDEND};
  2341.  
  2342.        int attr[NUMCHECKBOXCOLORS];
  2343.        WPOINTER w;
  2344.  
  2345.        main()
  2346.        {
  2347.          WindowInitializeSystem();
  2348.          FormInitializeSystem();
  2349.          WindowSaveInitial(0);
  2350.  
  2351.  
  2352.          Page 36        The C Data Forms Library               Page 36
  2353.  
  2354.          w = WindowInitialize(BORDER,1,1,78,22,COLOR1,COLOR1,SINGLEBOX);
  2355.          WindowOpen(w);
  2356.  
  2357.          /* Initialize form */
  2358.          form = FormInitialize(w,field,FORM_HIGHLIGHT);
  2359.  
  2360.          attr[NORMATTR]    = COLOR1;
  2361.          attr[HIATTR]      = COLOR2;
  2362.          attr[HOTATTR]     = COLOR3;
  2363.          attr[UNAVAILATTR] = COLOR4;
  2364.  
  2365.          FormSetCheckboxField(form,1,checkbox_entry,'X',1,attr);
  2366.  
  2367.        }
  2368.  
  2369.        The above call to FormSetCheckboxField() uses the FORMPTR form and
  2370.        field entry 1 (this is the CHECKBOX field).  The array,
  2371.        checkbox_entry, is used as the array of CHECKBOX_ENTRY's.  The
  2372.        'X' character is used as the checkbox character.  This character is
  2373.        usually used for checkbox fields, but you can use any ASCII
  2374.        character you desire (as stated before, I highly recommend NOT
  2375.        using the space character!).
  2376.  
  2377.        If there are no errors, FormSetCheckboxField() and will return
  2378.        NO_ERROR.
  2379.  
  2380.        If there are errors the return value is one of the following
  2381.  
  2382.        UNDEFINED_FORM if the FORMPTR does not exist.
  2383.  
  2384.        UNDEFINED_FIELD if the field entry does not exist.
  2385.  
  2386.        NO_HEAP_MEM if there is not enough memory to allocate for the
  2387.        internal checkbox field data structure.
  2388.  
  2389.  
  2390.  
  2391.        Deactivating and Activating Checkbox Entries
  2392.        --------------------------------------------
  2393.  
  2394.        If FormSetCheckboxField() is successful, all of the checkbox
  2395.        entries are available for the user to choose from.  However, there
  2396.        may be situations where you may want some options disabled.  To
  2397.        disable checkbox entries use the FormDeactivateCheckboxEntry()
  2398.        function.  Here is the prototype to the function:
  2399.  
  2400.        int FormDeactivateCheckboxField(FORMPTR form, int entry,
  2401.                                        int checkboxnum)
  2402.  
  2403.        The first two arguments are the form and entry number of where to
  2404.        find the checkbox entry.  The last argument is the entry in the
  2405.        checkbox field to deactivate.  The reason for using the form and
  2406.        entry to find the checkbox field is that you can use the same
  2407.        checkbox field in different forms.  Therefore you must supply the
  2408.  
  2409.  
  2410.  
  2411.  
  2412.          Page 37        The C Data Forms Library               Page 37
  2413.  
  2414.        form and entry number to find the checkbox field.  Once the
  2415.        checkbox entry is found, the prompt string for the desired checkbox
  2416.        entry takes on the UNAVAILATTR color.
  2417.  
  2418.        To reactivate a field, the FormActivateCheckboxEntry() function is
  2419.        used.  Here is the prototype:
  2420.  
  2421.        int FormActivateCheckboxEntry(FORMPTR form, int entry,
  2422.                                      int checkboxnum)
  2423.  
  2424.        The arguments have the same definition as the
  2425.        FormDeactivateCheckboxEntry().  The checkbox entry is automatically
  2426.        given its NORMATTR color.
  2427.  
  2428.  
  2429.        Retrieving the checkbox selection
  2430.        ---------------------------------
  2431.  
  2432.        To find out whether a checkbox entry was selected, use the
  2433.        FormGetCheckboxChoice() function.  This function returns 1 if the
  2434.        entry is selected, 0 otherwise.  Checkbox entries are numbered
  2435.        from 1 to the highest entry.  Entries are numbered as they are
  2436.        ordered in the CHECKBOX_ENTRY array.  Here is the prototype to the
  2437.        function:
  2438.  
  2439.        int FormGetCheckboxChoice(FORMPTR form, int entry, int cboxentry)
  2440.  
  2441.        The arguments are the form and field entry where the checkbox
  2442.        field is defined.  The last argument is the checkbox entry to
  2443.        test to see if it was selected.  Here is a small example:
  2444.  
  2445.        #include "cwlform.h"
  2446.        #define COLOR1 CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  2447.        #define COLOR2 CREATE_VIDEO_ATTRIBUTE(BLACK_,LIGHTWHITE_)
  2448.        #define COLOR3 COLOR2
  2449.        #define COLOR4 COLOR1
  2450.  
  2451.        CHECKBOX_ENTRY checkbox_entry[] = {"[ ] Check 1",'1',1,1,1,2,
  2452.                                           "[ ] Check 2",'2',2,1,2,2,
  2453.                                           "[ ] Check 3",'3',3,1,3,2,
  2454.                                           CWL_NULL};
  2455.        FORMPTR form;
  2456.        FIELD_ENTRY field[] = {CHECKBOX,0,0,"",' ',0,0,NO_FIELD_OPTIONS,
  2457.                               0,0,"", FIELDEND};
  2458.  
  2459.        int attr[NUMCHECKBOXCOLORS];
  2460.        WPOINTER w;
  2461.  
  2462.        main()
  2463.        {
  2464.          int i;
  2465.          WindowInitializeSystem();
  2466.          FormInitializeSystem();
  2467.          WindowSaveInitial(0);
  2468.  
  2469.  
  2470.  
  2471.  
  2472.          Page 38        The C Data Forms Library               Page 38
  2473.  
  2474.          w = WindowInitialize(BORDER,1,1,78,22,COLOR1,COLOR1,SINGLEBOX);
  2475.          WindowOpen(w);
  2476.  
  2477.          /* Initialize form */
  2478.          form = FormInitialize(w,field,FORM_HIGHLIGHT|FORM_STATIC);
  2479.  
  2480.          attr[NORMATTR]    = COLOR1;
  2481.          attr[HIATTR]      = COLOR2;
  2482.          attr[HOTATTR]     = COLOR3;
  2483.          attr[UNAVAILATTR] = COLOR4;
  2484.  
  2485.          FormSetCheckboxField(form,1,checkbox_entry,'X',attr);
  2486.          WindowWriteCenterString(w,
  2487.             "Hit TAB to accept, Space Bar to toggle, Arrow keys to change"
  2488.             "choice",4);
  2489.  
  2490.          FormGetInput(form,1,1);
  2491.          WindowMoveCursor(w,6,1);
  2492.          for (i=1; i<=3; i++)
  2493.            VideoPrintf("Checkbox choice %d was %s chosen\n",i,
  2494.                         FormGetCheckboxChoice(form,1,i)?"":"not");
  2495.        }
  2496.  
  2497.        The example above sets up a checkbox field, gets the input from the
  2498.        form, and then loops to see if any checkboxes were selected.  The
  2499.        string "not" is printed if FormGetCheckboxChoice() returns 0, else
  2500.        an empty string is printed.  FormGetCheckboxChoice() can be called
  2501.        at any time, even in user-defined functions that may be performed
  2502.        while the form is active.
  2503.  
  2504.        FormGetCheckboxChoice() returns 1 if the choice was selected, 0
  2505.        otherwise.
  2506.  
  2507.        If there are errors the return value is one of the following
  2508.  
  2509.        UNDEFINED_FORM if the FORMPTR does not exist.
  2510.  
  2511.        UNDEFINED_FIELD if the field entry does not exist.
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.  
  2531.  
  2532.          Page 39        The C Data Forms Library               Page 39
  2533.  
  2534.                         GETTING INPUT FROM A FORM
  2535.                         -------------------------
  2536.  
  2537.        The following section discusses how to call functions that process
  2538.        the input form.
  2539.  
  2540.  
  2541.        FormGetInput()
  2542.        --------------
  2543.  
  2544.        The FormGetInput() function processes a form.  Here is a
  2545.        prototype:
  2546.  
  2547.        int FormGetInput(FORMPTR form, int rank, int start)
  2548.  
  2549.                                        or
  2550.  
  2551.        int FormGetInput(FORMPTR form, int rank, int start, WPOINTER w)
  2552.  
  2553.  
  2554.        The first prototype is for non-virtual forms (regular windows are
  2555.        used).
  2556.  
  2557.        The second prototype is for virtual forms.  The second prototype's
  2558.        last argument is a pointer to window.  This window is the viewport
  2559.        that is currently assigned to the virtual window used to
  2560.        initialize the FIELD_ENTRY's.  This parameter is necessary since
  2561.        the form manager only knows what the virtual window is, and has no
  2562.        record of the viewport (since a virtual window can have multiple
  2563.        viewports).
  2564.  
  2565.        The first argument to FormGetInput() is the pointer to a form.
  2566.        This form must have been previously initialized with
  2567.        FormInitialize().
  2568.  
  2569.        The second argument is the rank of the window the form is going to
  2570.        be displayed on.
  2571.  
  2572.        The third argument is the field entry to start the input from.
  2573.        Field entries are numbered from 1 to the highest field defined in
  2574.        the form.  If the field is protected, a circular search for the
  2575.        next available field is done.  For example , if there are 6
  2576.        fields, and field 5 is protected, field 6 is the next available
  2577.        field.  However if field 6 is protected, field 1 is the next
  2578.        available field.
  2579.  
  2580.        The fourth argument, as discussed above, is an optional argument.
  2581.        This argument must be used if you are using a virtual form.
  2582.  
  2583.        If there are no errors, FormGetInput() returns NO_ERROR.
  2584.  
  2585.        If there are errors, FormGetInput() returns one of the following
  2586.        and sets window_error_code to one these values:
  2587.  
  2588.        UNDEFINED_FORM if the FORMPTR does not exist.
  2589.  
  2590.        BAD_WINDOW if the viewport window does not exist.
  2591.  
  2592.          Page 40        The C Data Forms Library               Page 40
  2593.  
  2594.        #include "cwlform.h"
  2595.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  2596.  
  2597.        FIELD_ENTRY field_array[] =
  2598.  
  2599.                /* define first field entry */
  2600.  
  2601.                {INTEGER,1,20,"___",'_',1,3,FIELD_RJUSTIFY,NORM,"3[0-9]",
  2602.                STRING, 2, 20, "__________", '_', 0, 10, NO_FIELD_OPTIONS,
  2603.                        1,NORM, "10.",
  2604.                INTEGER,3, 20, "__", '_', 2, 2,NO_FIELD_OPTIONS, 1,NORM,
  2605.                        "2[0-9]",
  2606.                DOUBLE,4, 20, "_______",'_',1,7,FIELD_COMMA|FIELD_LJUSTIFY,
  2607.                        1,NORM,"7[0-9/.]",
  2608.                CHAR, 5, 20,"_", '_', 1, 1, FIELD_UPPERCASE, 1,NORM,
  2609.                "[YyNn]",
  2610.                FIELDEND};
  2611.  
  2612.        WPOINTER w;
  2613.        FORMPTR form;
  2614.        main()
  2615.        {
  2616.          WindowInitializeSystem();
  2617.          FormInitializeSystem();
  2618.          FormInitializeFloat();
  2619.          WindowSaveInitial(0);
  2620.          w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
  2621.          WindowOpen(w);
  2622.          /* Initialize with WPOINTER */
  2623.  
  2624.          form = FormInitialize(w,  /* window to assign form to */
  2625.                                field_array, /* array of fields */
  2626.                                NO_FORM_OPTIONS); /* form options */
  2627.          if (form == FORM_NULL_PTR)
  2628.          {
  2629.            printf("Form could not be initialized");
  2630.            exit(0);
  2631.          }
  2632.          FormGetInput(form,1,1);   /* Get Input for the form */
  2633.        }
  2634.  
  2635.  
  2636.        Virtual Form Scrolling
  2637.        ----------------------
  2638.  
  2639.        If the form is a virtual form, the form is scrolled automatically
  2640.        to the desired field if the field is not currently in the
  2641.        viewport.  If the form has to be scrolled up or down, the field
  2642.        will come into view on the last line of the viewport or the first
  2643.        line, depending on whether the form was scrolled up or down to
  2644.        bring the field into view.
  2645.  
  2646.        If the form has to be scrolled left or right to bring the field in
  2647.        view, the field will either be brought in so that it is right
  2648.        justified in the viewport, or will appear on the left edge of the
  2649.        viewport depending on whether the form manager had to scroll the
  2650.        form left or right.
  2651.  
  2652.          Page 41        The C Data Forms Library               Page 41
  2653.  
  2654.        Editing Input
  2655.        -------------
  2656.        When getting input from a form, the following key definitions are
  2657.        used as the defaults:
  2658.  
  2659.                                                      Offset in Key
  2660.        Function                      Key                Table
  2661.        --------                      ---             -------------
  2662.        Move cursor left          Left Arrow         FIELD_MOVELEFT_KEY
  2663.  
  2664.        Move cursor right         Right Arrow        FIELD_MOVERIGHT_KEY
  2665.  
  2666.        Delete character          Del (on keypad)    FIELD_DELNOMOVE_KEY
  2667.  
  2668.        Toggle Insert/Overwrite   Insert (on keypad) FIELD_INSTOGGLE_KEY
  2669.  
  2670.        Erase Input               ^E                 FIELD_ERASE_KEY
  2671.  
  2672.        Destructive backspace     Backspace          FIELD_BACKSPACE_KEY
  2673.  
  2674.        Accept Input and goto     Enter              FIELD_ACCEPT_KEY
  2675.        next field.
  2676.  
  2677.        Accept default and        Not Assigned       FIELD_ACCEPTDEFAULT_KEY
  2678.        return
  2679.  
  2680.        Go to first column        Home               FIELD_HOME_KEY
  2681.  
  2682.        Move cursor to last       End                FIELD_END_KEY
  2683.        character
  2684.  
  2685.        Go to previous field      Up Arrow           FIELD_PREVFIELD_KEY
  2686.  
  2687.        Go to next field          Down Arrow         FIELD_NEXTFIELD_KEY
  2688.  
  2689.        Toggle Field              Space Bar          FIELD_TOGGLE_KEY
  2690.  
  2691.        Button Accept key         Enter              BUTTON_ACCEPT_KEY
  2692.  
  2693.        Button Move to next       Right Arrow        BUTTON_NEXTFIELD_KEY
  2694.        field
  2695.  
  2696.        Button Move to prev       Left Arrow         BUTTON_PREVFIELD_KEY
  2697.        field
  2698.  
  2699.        Move Radio button to      Down  Arrow        RADIO_NEXTENTRY_KEY
  2700.        next entry
  2701.  
  2702.        Move Radio button to      Up   Arrow         RADIO_PREVENTRY_KEY
  2703.        previous entry
  2704.  
  2705.  
  2706.        Move to next field from   Tab                RADIO_NEXTFIELD_KEY
  2707.        radio field
  2708.  
  2709.        Move to previous field    ShiftTab           RADIO_PREVFIELD_KEY
  2710.        from radio field
  2711.  
  2712.          Page 42        The C Data Forms Library               Page 42
  2713.  
  2714.        Select/deselect           Space Bar          CHECKBOX_CHOICE_KEY
  2715.        checkbox entry
  2716.  
  2717.        Move checkbox cursor to   Down  Arrow        CHECKBOX_NEXTENTRY_KEY
  2718.        next checkbox entry
  2719.  
  2720.        Move checkbox cursor to   Up   Arrow         CHECKBOX_PREVENTRY_KEY
  2721.        previous checkbox entry
  2722.  
  2723.        Move to next field from   Tab                CHECKBOX_NEXTFIELD_KEY
  2724.        checkbox field
  2725.  
  2726.        Move to previous field    ShiftTab           CHECKBOX_PREVFIELD_KEY
  2727.        checkbox field
  2728.  
  2729.        Accept form               ^S                 FORM_EXIT_ACCEPT_KEY
  2730.  
  2731.        Escape form               Escape             FORM_EXIT_CLEAR_KEY
  2732.  
  2733.        Clear Form                ^End               FORM_CLEAR_KEY
  2734.  
  2735.        Here is a list of what the key functions perform:
  2736.  
  2737.  
  2738.        Move cursor left - Moves the cursor left one character.  If the
  2739.                           beginning of the input field is encountered the
  2740.                           cursor is not moved.
  2741.  
  2742.        Move cursor right - Moves the cursor right one character.  If the
  2743.                            end of the input field is encountered, the
  2744.                            cursor is not moved.
  2745.  
  2746.        Delete character at cursor - Deletes the character at the position
  2747.                                     of the cursor.  If in insert mode,
  2748.                                     any input to the right of the
  2749.                                     cursor is moved one character to
  2750.                                     the left.  If in overwrite mode, no
  2751.                                     characters are moved.
  2752.  
  2753.  
  2754.        Toggle Insert/Overwrite Mode - toggles the input between insert and
  2755.                                       overwrite mode.  If in insert mode,
  2756.                                       the default cursor is an underline
  2757.                                       cursor.  If in overwrite mode, the
  2758.                                       default cursor is a full block.
  2759.  
  2760.        Erase Input - Deletes all characters inputted and moves the cursor
  2761.                        to the first input position.
  2762.  
  2763.        Destructive Backspace - deletes the character immediately to the
  2764.                                left of the cursor and moves the cursor to
  2765.                                the left one character. If insert mode is
  2766.                                on, the characters from the current cursor
  2767.                                position to the end of the input field are
  2768.                                also moved.
  2769.  
  2770.  
  2771.  
  2772.          Page 43        The C Data Forms Library               Page 43     
  2773.  
  2774.        Accept string - Accepts the string that is inputted and returns the
  2775.                        string.  Also goes to next field by default.
  2776.  
  2777.        Accept default and return - Returns the default string given to the
  2778.                                    input routine.
  2779.  
  2780.        Go to first column in field - Moves cursor to the first input
  2781.                                      position.
  2782.  
  2783.        Go to last character in field - Moves cursor to the last character
  2784.                                        in the current input string.
  2785.  
  2786.        Go to previous field - Moves input cursor to the first character in
  2787.                               the previous field.  If field is field 1 or
  2788.                               first available field, the input cursor is
  2789.                               moved to the last input field if the
  2790.                               FORM_WRAP option is on, otherwise the input
  2791.                               cursor is not moved.
  2792.  
  2793.        Go to next field - Moves the input cursor to the first character in
  2794.                           the next field in sequence.
  2795.  
  2796.        Toggle field     - Displays next choice in a TOGGLE field.  Only is
  2797.                           active for TOGGLE field.  Undefined for other
  2798.                           fields.
  2799.  
  2800.        Button Accept    - Accepts the BUTTON field and will perform
  2801.                           whatever the buttons return value was.
  2802.  
  2803.        Button Move to next field  - Moves to the next field from a button
  2804.                                     Does not accept the button field.
  2805.  
  2806.        Button move to prev. field  - Moves to previous field from a button
  2807.                                      field.  Does not accept the button
  2808.                                      field.
  2809.  
  2810.        Move Radio button to next radio entry - moves the highlight in the
  2811.                                                radio entry to the next
  2812.                                                available radio entry.
  2813.  
  2814.        Move Radio button to prev. radio entry - moves the highlight in
  2815.                                                 the radio entry to the
  2816.                                                 previous radio entry.
  2817.  
  2818.        Move to next field from radio - moves to the next field from a
  2819.                                        radio field.
  2820.  
  2821.        Move to prev. field from radio - moves to the previous field from a
  2822.                                         radio field.
  2823.  
  2824.        Select/Deselect checkbox entry - toggles checkbox entry for
  2825.                                         selection/delection.
  2826.  
  2827.        Move to next checkbox entry - moves the highlight to the next
  2828.                                      checkbox entry.
  2829.  
  2830.  
  2831.  
  2832.          Page 44        The C Data Forms Library               Page 44     
  2833.  
  2834.        Move to prev. checkbox entry - moves the highlight to the previous
  2835.                                       checkbox entry.
  2836.  
  2837.        Move to next field from checkbox - moves to the next field from a
  2838.                                           checkbox field.
  2839.  
  2840.        Move to prev. field from checkbox - moves to the previous field
  2841.                                            from a checkbox field.
  2842.  
  2843.        Accept form -      Accepts the input to a form, and exits
  2844.                           processing the form.
  2845.  
  2846.        Escape form and do not accept - Exits form without accepting the
  2847.                                        input to any fields.
  2848.  
  2849.        Clear Form - clears all input in a form and moves the cursor to the
  2850.                     first available field.
  2851.  
  2852.  
  2853.        Changing the Editing Key definitions globally using the
  2854.        form_edit_key table
  2855.        -------------------
  2856.  
  2857.        You can change the key definitions globally (all fields will have
  2858.        the same key definitions) by changing the form_edit_key array of
  2859.        values.  The mapped position is the offset in a table of field key
  2860.        functions.  By changing the value there, you can change the keys
  2861.        used to perform these functions.  If you do want to change these
  2862.        keys, I recommend using the key definitions found in the keycodes.h
  2863.        file.  For example, if you wanted tab key to be the advance to next
  2864.        field key you would do the following:
  2865.  
  2866.                form_edit_key[FIELD_NEXTFIELD_KEY] = TAB;
  2867.  
  2868.        The table of key functions is stored in the array form_edit_key.
  2869.        The TAB definition is found in the keycodes.h file.  To totally
  2870.        undefine a key definition, assign a 0 to the desired array position
  2871.        in window_edit_key.  For example:
  2872.  
  2873.                form_edit_key[FIELD_DELNOMOVE_KEY] = 0;
  2874.  
  2875.        undefines the delete character at cursor definition.
  2876.  
  2877.        When changing keys, make sure that the definitions all have unique
  2878.        key combinations.  If you desire more keystrokes for a particular
  2879.        key function, see Undefined Form Keystroke Processing below.
  2880.  
  2881.  
  2882.        Changing the Editing Key definitions using FormAssignFieldKeys()
  2883.        ----------------------------------------------------------------
  2884.  
  2885.        The FormAssignFieldKeys() assigns a key definition to a particular
  2886.        field.  In other words, each field can have its own set of editing
  2887.        key definitions.  Here is the prototype:
  2888.  
  2889.        int FormAssignFieldKeys(FORMPTR form, int entrynum,
  2890.                                unsigned *keydef)
  2891.  
  2892.          Page 45        The C Data Forms Library               Page 45     
  2893.  
  2894.        The first argument is the pointer to the form.  The form must have
  2895.        been successfully initialized with FormInitialize().
  2896.  
  2897.        The second argument is the field entry number to assign these key
  2898.        definitions to.  As stated before, entry numbers are labeled from 1
  2899.        to the highest entry number in the form.
  2900.  
  2901.        The third argument is an array of key definitions.  This array must
  2902.        be analogous to the form_edit_key array.
  2903.  
  2904.  
  2905.        Example:
  2906.  
  2907.        #include "cwlform.h"
  2908.        #include <string.h>
  2909.  
  2910.        /*  ...  define everything ... */
  2911.  
  2912.        unsigned newkeys[NUMFORMKEYS];
  2913.        FORMPTR form;
  2914.        FIELD_ENTRY field_entry[] = { /* .. Field definitions ... */ };
  2915.        WPOINTER w;
  2916.  
  2917.        main()
  2918.        {
  2919.          WindowInitializeSystem();
  2920.          FormInitializeSystem();
  2921.        /* ... assume Form Initialization stuff has been done ... */
  2922.  
  2923.        /* copy old key definitions to the new array */
  2924.          memcpy(newkeys,form_edit_key,sizeof(form_edit_key));
  2925.  
  2926.        /* assign desired keys */
  2927.          newkeys[FIELD_NEXT_KEY] = TAB;
  2928.          newkeys[FIELD_PREV_KEY] = SHIFTTAB;
  2929.  
  2930.        /* Assign this key definition to second field entry */
  2931.          FormAssignFieldKeys(form,2,newkeys);
  2932.  
  2933.        }
  2934.  
  2935.  
  2936.        Note that the constant NUMFORMKEYS was used to make sure that our
  2937.        newkeys array was large enough to hold all the key definitions.
  2938.        Also note the shortcut that was taken with the memcpy() function.
  2939.        This copied all the old key definitions to the newkeys array.  Both
  2940.        the newkeys array and the form_edit_key array are guaranteed to be
  2941.        the same size if the constant NUMFORMKEYS is used.
  2942.  
  2943.        If there are no errors, FormAssignFieldKeys() returns NO_ERROR.
  2944.  
  2945.        If there are errors, FormAssignFieldKeys() returns one of the
  2946.        following and sets window_error_code to one these values:
  2947.  
  2948.        UNDEFINED_FORM if the FORMPTR does not exist.
  2949.  
  2950.        UNDEFINED_FIELD if the field entry does not exist
  2951.  
  2952.          Page 46        The C Data Forms Library               Page 46     
  2953.  
  2954.        Traversing fields and the FORM_HIGHLIGHT option
  2955.        -----------------------------------------------
  2956.  
  2957.        When going from field to field, you can have each field take on the
  2958.        field color only when they are the active field (field currently
  2959.        being input).  This will happen if the FORM_HIGHLIGHT option is on.
  2960.        If the field is not the active field, the field takes on the same
  2961.        color as the window or the viewport text color.
  2962.  
  2963.        If the FORM_HIGHLIGHT option is off, each field will take on its
  2964.        field color even if they are not the current field.
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.  
  2990.  
  2991.  
  2992.  
  2993.  
  2994.  
  2995.  
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.          Page 47        The C Data Forms Library               Page 47     
  3013.  
  3014.              ASSIGNING VALUES TO AND RETRIEVING VALUES FROM A FORM
  3015.              -----------------------------------------------------
  3016.  
  3017.        When you edit an input field, you are entering just a string of
  3018.        characters.  The C Data Forms Library's form manager will
  3019.        automatically convert these strings to the correct data type, and
  3020.        assign these values to specified variables when a form is exited,
  3021.        or whenever you want to retrieve the data.
  3022.  
  3023.        The field type determines what type of conversion will be done.
  3024.        The supported types are the normal C types.  The SUBFORM,
  3025.        VSUBFORM, BUTTON, RADIO, and CHECKBOX fields do not have a return
  3026.        type.  The LIST field returns the string in the popup menu
  3027.        that was selected.  The TOGGLE field returns the string that was
  3028.        chosen in the toggle field list.
  3029.  
  3030.  
  3031.        FormSetFieldVariable()
  3032.        ----------------------
  3033.  
  3034.        The FormSetFieldVariable() function assigns a variable to a
  3035.        particular field in a form.  When the form is exited, the data is
  3036.        converted and transferred to the variable specified.  Here is the
  3037.        prototype:
  3038.  
  3039.        int FormSetFieldVariable(FORMPTR form, int entrynum,
  3040.                                     void *uservar, int display)
  3041.  
  3042.        The first argument is the pointer to a form.
  3043.        The second argument is the field entry to assign the user variable
  3044.        to.
  3045.  
  3046.        The third argument is a pointer to the user variable.
  3047.        The fourth argument is a flag to tell the form manager whether to
  3048.        display the value in the variable on the form.  If display is TRUE,
  3049.        the variable's value is automatically displayed in the form.  If
  3050.        display is FALSE, the variable's value is not displayed in the
  3051.        form.  No matter what the last argument is, the address of the
  3052.        variable is assigned to the form.
  3053.  
  3054.        If the field type is TOGGLE or LIST, these types translate to
  3055.        string types because a string will ultimately be displayed in the
  3056.        field when a selection is made for these two types.  SUBFORM's,
  3057.        VSUBFORM's, BUTTON's, RADIO's and CHECKBOXes have no corresponding
  3058.        C data type, therefore you cannot assign a variable to these field
  3059.        types.
  3060.  
  3061.        Example:
  3062.  
  3063.        #include "cwlform.h"
  3064.        #include <string.h>
  3065.  
  3066.        #define NORM   CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  3067.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(_WHITE,_BLACK)
  3068.  
  3069.        FORMPTR form;
  3070.  
  3071.  
  3072.          Page 48        The C Data Forms Library               Page 48     
  3073.  
  3074.        FIELD_ENTRY field_entry[] =
  3075.        {INTEGER,1,20,"_____",' ',1,5,NO_FIELD_OPTIONS,1,REVERSE,"5[0-9]",
  3076.         ULINTEGER,2,20,"_________",' ',1,9,NO_FIELD_OPTIONS,1,REVERSE,
  3077.                  "9[0-9]",
  3078.         FIELDEND};
  3079.  
  3080.        WPOINTER w;
  3081.  
  3082.        main()
  3083.        {
  3084.          int intvar = 123;  /* define integer and long variables */
  3085.          unsigned long lvar = 456L;
  3086.          WindowInitializeSystem();
  3087.          FormInitializeSystem();
  3088.          WindowSaveInitial(0);
  3089.          w = WindowInitialize(BORDER,1,1,60,4,NORM,NORM,SINGLEBOX);
  3090.  
  3091.          WindowOpen(w);
  3092.          form = FormInitialize(w,field_entry,FORM_HIGHLIGHT);
  3093.  
  3094.          /* Set user variables */
  3095.          FormSetFieldVariable(form,1,&intvar,TRUE);
  3096.          FormSetFieldVariable(form,2,&lvar,TRUE);
  3097.  
  3098.          FormGetInput(form,1,1);
  3099.  
  3100.          VideoPrintf(
  3101.          "The value of intvar is %d.\nThe value of lvar is %ul",
  3102.              intvar,lvar);
  3103.        }
  3104.  
  3105.        When the form is exited, the variables intvar and lvar have the
  3106.        values automatically converted.
  3107.  
  3108.        If you change the value of a variable that is assigned to a field,
  3109.        the field is not updated.  Use the FormPutFieldData() to change
  3110.        the value of a field.
  3111.  
  3112.        Warning!  You must make sure that you assign the pointer to a
  3113.        variable of the correct type.  If not, you may overwrite memory
  3114.        when the conversion takes place.
  3115.  
  3116.  
  3117.        Placing input in a form with FormPutFieldData()
  3118.        -----------------------------------------------
  3119.  
  3120.        You can write the value of a variable or an expression to a field
  3121.        at anytime using the FormPutFieldData() function.  Here is the
  3122.        prototype:
  3123.  
  3124.        int FormPutFieldData(FORMPTR form, int entry, ...)
  3125.  
  3126.        The first argument is the form, and the second is the entry number.
  3127.        The last argument third is the value to write to the field.  Note
  3128.        that the ellipses are used when prototyping the last argument.  The
  3129.        reason for this is that the variable or expression can be of any
  3130.        type, therefore the undefined third argument.
  3131.  
  3132.          Page 49        The C Data Forms Library               Page 49     
  3133.  
  3134.        You should make sure that the variable/expression translates to the
  3135.        same data type as the field type.  There is no harm done if you
  3136.        have an expression of a different type than the field, but you may
  3137.        get weird characters in the field when it is displayed.
  3138.  
  3139.        Here is an example:
  3140.  
  3141.        #include "cwlform.h"
  3142.  
  3143.        /* assume everything is initialized */
  3144.  
  3145.        main()
  3146.        {
  3147.          int intvar = 0;
  3148.          long lvar  = 2;
  3149.  
  3150.          /*...*/
  3151.          FormPutFieldData(form,1,intvar); /* place value of intvar in
  3152.                                              entry 1 */
  3153.          FormPutFieldData(form,2,lvar);   /* place value of lvar in
  3154.                                              entry 2 */
  3155.          FormPutFieldData(form,1,3+5*6); /* place value of expression in
  3156.                                             entry 1 */
  3157.  
  3158.          /* ... */
  3159.        }
  3160.  
  3161.        If there are errors, FormPutFieldData() returns one of the
  3162.        following and sets window_error_code to one these values:
  3163.  
  3164.        UNDEFINED_FORM if the FORMPTR does not exist.
  3165.  
  3166.        UNDEFINED_FIELD if the field entry does not exist
  3167.  
  3168.  
  3169.        Retrieving Input with FormGetFieldData()
  3170.        ----------------------------------------
  3171.  
  3172.        You can retrieve and convert the string entered in a field at any
  3173.        time, including if the form has been exited, with the
  3174.        FormGetFieldData() function.  Here is the prototype:
  3175.  
  3176.        int FormGetFieldData(FORMPTR form, int entrynum, void *uservar)
  3177.  
  3178.        The first and second arguments are the form and field entry number,
  3179.        respectively.
  3180.  
  3181.        The third argument is the pointer to the desired variable to assign
  3182.        this value to.
  3183.  
  3184.        Example:
  3185.  
  3186.        #include "cwlform.h"
  3187.  
  3188.        FORMPTR form;
  3189.        FIELD_ENTRY field[] = {INTEGER, /* other initializations */ };
  3190.        int myvar;
  3191.  
  3192.          Page 50        The C Data Forms Library               Page 50     
  3193.  
  3194.        main()
  3195.        {
  3196.          /* assume everything is initialized */
  3197.  
  3198.          /* get what was entered in field 1 and copy converted
  3199.             value to myvar */
  3200.          FormGetFieldData(form,1,&myvar);
  3201.        }
  3202.  
  3203.        Warning!  You must make sure that you assign the pointer to a
  3204.        variable of the correct type.  If not, you may overwrite memory
  3205.        when the conversion takes place.
  3206.  
  3207.        If there are no errors, FormGetFieldData() returns NO_ERROR.
  3208.  
  3209.        If there are errors, FormGetFieldData() returns one of the
  3210.        following and sets window_error_code to one these values:
  3211.  
  3212.        UNDEFINED_FORM if the FORMPTR does not exist.
  3213.  
  3214.        UNDEFINED_FIELD if the field entry does not exist
  3215.  
  3216.  
  3217.  
  3218.  
  3219.        Pre-filling a form with default data with FormInitializeFieldData()
  3220.        -------------------------------------------------------------------
  3221.  
  3222.        You can pre-fill a form with data before you start getting input
  3223.        from the form.  The only restriction is that the data must be in
  3224.        string form.
  3225.  
  3226.        The FormInitializeFieldData() partially or totally initializes a
  3227.        form with default data.  The data must be in string form.  Here is
  3228.        the prototype:
  3229.  
  3230.        int FormInitializeFieldData(FORMPTR form, char **data, int start,
  3231.                                    int end)
  3232.  
  3233.        The first argument is the pointer to a form.
  3234.  
  3235.        The second argument is a pointer to an array of characters.  This
  3236.        will be dealt with in depth later on.
  3237.  
  3238.        The third and fourth arguments are the starting entry to initialize
  3239.        and the ending entry to initialize.  FormInitializeFieldData()
  3240.        initializes a range of field entries.  If the ending entry number
  3241.        is less than the starting entry number, the ending entry number
  3242.        will be made equal to the starting entry number.
  3243.  
  3244.  
  3245.        Setting up array of strings using Allocate2DArray() function
  3246.        ------------------------------------------------------------
  3247.  
  3248.        There are many ways to set up the array of strings required for the
  3249.        second argument to FormInitializeFieldData().  Here are various
  3250.        methods of assigning "123" to an array of strings:
  3251.  
  3252.          Page 51        The C Data Forms Library               Page 51     
  3253.  
  3254.        /* Method 1 */
  3255.  
  3256.        #include <string.h>
  3257.        char data[5][4];
  3258.        FORMPTR form;
  3259.  
  3260.        main()
  3261.        {
  3262.          int i;
  3263.          /* ... assume form already initialized */
  3264.  
  3265.          /* copy "123" to data array */
  3266.          for (i=0;i<4;i++)
  3267.            strcpy(data[i],"123");
  3268.          FormInitializeFieldData(form,data,1,5);
  3269.        }
  3270.  
  3271.  
  3272.  
  3273.        /* Method 2 */
  3274.  
  3275.        #include <string.h>
  3276.        char *data[5] = {
  3277.                        "123",
  3278.                        "123",
  3279.                        "123",
  3280.                        "123",
  3281.                        "123" };
  3282.  
  3283.  
  3284.        main()
  3285.        {
  3286.  
  3287.          /* ... assume form already initialized */
  3288.          FormInitializeFieldData(form,data,1,5);
  3289.        }
  3290.  
  3291.  
  3292.  
  3293.        /* Method 3 */
  3294.  
  3295.        #include "cwlform.h"
  3296.        char **data;
  3297.  
  3298.  
  3299.  
  3300.        main()
  3301.        {
  3302.          data = (char **)Allocate2DArray(5,4,sizeof(char));
  3303.          for (i=0;i<5;i++)
  3304.            strcpy(data[i],"123");
  3305.          FormInitializeFieldData(form,data,1,5);
  3306.        }
  3307.  
  3308.        The first two methods are self-explanatory, or if they are not, any
  3309.        elementary book on C programming will explain the methods used to
  3310.        initialize an array of strings.
  3311.  
  3312.          Page 52        The C Data Forms Library               Page 52     
  3313.  
  3314.        The third method dynamically allocates memory for a two dimensional
  3315.        array.  Note the use of the function Allocate2DArray().  This
  3316.        function allocates a two dimensional array from the heap.  The
  3317.        first and second arguments to this function are the number of rows
  3318.        and columns in the array, respectively.  The third argument is the
  3319.        size of each data element (in bytes) in the array.  Since we want
  3320.        to initialize a two dimensional array of five strings with 4
  3321.        characters for each string (you should allow an extra character for
  3322.        the terminating null for each string), the size of each element
  3323.        will be the size of one character.  Note the use of sizeof() to
  3324.        determine the size of a character.
  3325.  
  3326.        You can use Allocate2DArray() with any data type.  You must make
  3327.        sure that the return value is cast to the proper pointer type,
  3328.        since the returning data type is a void pointer (This rule is
  3329.        relaxed for C programs, but it is strictly enforced in C++
  3330.        programs).
  3331.  
  3332.        Allocate2DArray() returns a null pointer if it cannot allocate the
  3333.        memory desired.  You can allocate up to 64K of memory with this
  3334.        function.  To calculate the amount of memory that will be
  3335.        allocated, you should use the following formula:
  3336.  
  3337.                    rows X cols X sizeof(each data element)
  3338.  
  3339.        The prototype for this function is include in the window.h file.
  3340.        Since cwlform.h includes window.h, there was no need to explicitly
  3341.        include window.h in any of the examples.
  3342.  
  3343.        Freeing a two dimensional array with Free2DArray()
  3344.        --------------------------------------------------
  3345.  
  3346.        If you want to dispose of a two dimensional array allocated with
  3347.        Allocate2DArray(), you should use the Free2DArray() function.  The
  3348.        prototype is as follows:
  3349.  
  3350.                        void Free2DArray(void **array)
  3351.  
  3352.        The only argument is the pointer to the two dimensional array.
  3353.        Since this function does not return anything, you must make sure
  3354.        that you are actually freeing a valid two dimensional array.
  3355.  
  3356.  
  3357.        Using FormInitializeFieldData()
  3358.        -------------------------------
  3359.  
  3360.        As was stated above, FormInitializeFieldData() can totally or
  3361.        partially fill a form with default data.  The number of fields that
  3362.        will be filled is determined by the starting and ending field entry
  3363.        numbers, which are denoted by the third and fourth arguments to
  3364.        FormInitializeFieldData().  For instance if the starting entry is 1
  3365.        and the ending entry is 5, the form manager will start filling in
  3366.        the fields 1 through 5 with the data stored in the array of
  3367.        strings, which was passed as the second argument, to
  3368.        FormInitializeFieldData().  If a CWL_NULL is encountered in the
  3369.        array of strings before the last entry specified is reached,
  3370.  
  3371.  
  3372.          Page 53        The C Data Forms Library               Page 53     
  3373.  
  3374.        FormInitializeFieldData() will stop initializing fields and will
  3375.        return NO_ERROR.  FormInitializeFieldData() should be called before
  3376.        calling FormGetInput().
  3377.  
  3378.        #include "cwlform.h"
  3379.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  3380.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE,BLACK_)
  3381.  
  3382.        FIELD_ENTRY field_array[] =
  3383.        {INTEGER,1,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3384.                "3[0-9]",
  3385.        INTEGER,2,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3386.                "3[0-9]",
  3387.        STRING,3,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3388.                "3[0-9]",
  3389.        INTEGER,4,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3390.                "3[0-9]",
  3391.        UINTEGER,5,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3392.                "3[0-9]",
  3393.        CHAR,6,35,"_",'_',1,1,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3394.                "[YyNn]",
  3395.        CHAR,7,35,"_",'_',1,1,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3396.                "[YyNn]",
  3397.        INTEGER,8,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  3398.                "3[0-9]",
  3399.        FIELDEND};
  3400.  
  3401.        WPOINTER w;
  3402.        FORMPTR form;
  3403.        char *data[8] = {
  3404.                        "123",
  3405.                        "0",
  3406.                        "ABC",
  3407.                        "200",
  3408.                        "230",
  3409.                        "N",
  3410.                        "Y",
  3411.                        "100"};
  3412.  
  3413.        main()
  3414.        {
  3415.          WindowInitializeSystem();
  3416.          FormInitializeSystem();
  3417.          WindowSaveInitial(0);
  3418.          w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
  3419.          WindowOpen(w);
  3420.          /* Initialize with WPOINTER */
  3421.          form = FormInitialize(w,  /* window to assign form to */
  3422.                                field_array, /* array of fields */
  3423.                                FORM_HIGHLIGHT); /* form options */
  3424.  
  3425.          if (form == FORM_NULL_PTR)
  3426.          {
  3427.            printf("Form could not be initialized");
  3428.            exit(0);
  3429.          }
  3430.  
  3431.  
  3432.          Page 54        The C Data Forms Library               Page 54     
  3433.  
  3434.          FormInitializeFieldData(form,data,1,8);
  3435.          FormGetInput(form,1,1);   /* Get Input for the form */
  3436.        }
  3437.  
  3438.  
  3439.        If there are no errors, FormInitializeFieldData() returns NO_ERROR.
  3440.  
  3441.        If there are errors, FormInitializeFieldData() returns one of the
  3442.        following and sets window_error_code to one these values:
  3443.  
  3444.        UNDEFINED_FORM if the FORMPTR does not exist.
  3445.  
  3446.        UNDEFINED_FIELD if the starting field does not exist.
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.          Page 55        The C Data Forms Library               Page 55     
  3493.  
  3494.                              SETTING FIELD OPTIONS
  3495.                              ---------------------
  3496.  
  3497.        In the previous sections, the field options were set up during
  3498.        initialization of the field entries.  You can also set field
  3499.        options at any time.  If you want to set field options during form
  3500.        input there are some restrictions.
  3501.  
  3502.  
  3503.        FormSetFieldOptions()
  3504.        ---------------------
  3505.  
  3506.        The FormSetFieldOptions() function turns on or off field options.
  3507.        Here is the prototype:
  3508.  
  3509.        int FormSetFieldOptions(FORMPTR form, int entrynum, int options,
  3510.                                int flag)
  3511.  
  3512.        The first and second arguments are the form and the field entry
  3513.        number, respectively.
  3514.  
  3515.        The third arguments are the options desired.  The fourth arguments
  3516.        tell us whether to turn these options on or off.  If flag is equal
  3517.        to 1, the options are turned on.  If flag is 0, the options are
  3518.        turned off.
  3519.  
  3520.        The field options are the same options specified in the CREATING
  3521.        FIELD ENTRIES section above.  Multiple field options can be
  3522.        specified by using the bitwise OR (|) between field option
  3523.        constants, just as before.
  3524.  
  3525.        The field option that you would probably use this function for most
  3526.        of the time is the FIELD_PROTECT option.  As defined, if the
  3527.        FIELD_PROTECT option is on, the form manager will skip over this
  3528.        field and will go to the next available field.  You will probably
  3529.        want to toggle a field's FIELD_PROTECT option during input of a
  3530.        form.
  3531.  
  3532.        It is advised NOT to change the field options of a particular field
  3533.        if the field is currently being edited.  This may lead to undesired
  3534.        results.
  3535.  
  3536.        #include "cwlform.h"
  3537.  
  3538.        FORMPTR form;
  3539.  
  3540.        /* ... skip other initializations ... */
  3541.  
  3542.        main()
  3543.        {
  3544.          /* ... skip initializations ... */
  3545.          /* set field protect option */
  3546.          FormSetFieldOptions(form,1,FIELD_PROTECT,1);
  3547.  
  3548.          /* turn off field protect option */
  3549.          FormSetFieldOptions(form,1,FIELD_PROTECT,0);
  3550.        }
  3551.  
  3552.          Page 56        The C Data Forms Library               Page 56     
  3553.  
  3554.        If there are no errors, FormSetFieldOptions() returns NO_ERROR.
  3555.  
  3556.        If there are errors, FormSetFieldOptions() returns one of the
  3557.        following and sets window_error_code to one these values:
  3558.  
  3559.        UNDEFINED_FORM if the FORMPTR does not exist.
  3560.  
  3561.        UNDEFINED_FIELD if the field entry does not exist
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.          Page 57        The C Data Forms Library               Page 57     
  3613.  
  3614.                              SETTING FORM OPTIONS
  3615.                              --------------------
  3616.  
  3617.        In the previous sections, the form options were set up when
  3618.        FormInitialize() was called.  You can also set form options at any
  3619.        time, including during input of a form.
  3620.  
  3621.  
  3622.        FormSetOptions()
  3623.        ----------------
  3624.  
  3625.        The FormSetOptions() function turns on or off form options.  Here
  3626.        is the prototype:
  3627.  
  3628.                int FormSetOptions(FORMPTR form, int options, int flag)
  3629.  
  3630.        The first argument is the pointer to the form.
  3631.  
  3632.        The second argument are the options desired.  The third argument
  3633.        tells us whether to turn these options on or off.  If flag is equal
  3634.        to 1, the options are turned on.  If flag is 0, the options are
  3635.        turned off.
  3636.  
  3637.        The form options are the same options specified in the
  3638.        FormInitialize() function, which is described in the CREATING FIELD
  3639.        ENTRIES section above.  Multiple form options can be specified by
  3640.        using the bitwise OR (|) between form option constants, just as
  3641.        before.
  3642.  
  3643.        You should not use the FORM_VIRTUAL or FORM_HIGHLIGHT options in
  3644.        this function.  The FormInitialize() function uses these options to
  3645.        set up the form, and assumes the form will remain a virtual or
  3646.        windowed form throughout the life of the form.  The form manager
  3647.        also assumes that the FIELD_HIGHLIGHT option remains the same
  3648.        throughout the life of the form.
  3649.  
  3650.        #include "cwlform.h"
  3651.  
  3652.        FORMPTR form;
  3653.  
  3654.        /* ... skip other initializations ... */
  3655.  
  3656.        main()
  3657.        {
  3658.  
  3659.          /* ... skip initializations ... */
  3660.  
  3661.          form = FormInitialize( /* arguments to FormInitialize */ );
  3662.  
  3663.          /* set form checking option */
  3664.          FormSetOptions(form,1,FORM_CHECK_ON,1);
  3665.  
  3666.          /* turn off form checking option */
  3667.          FormSetOptions(form,1,FORM_CHECK_OFF,0);
  3668.        }
  3669.  
  3670.  
  3671.  
  3672.          Page 58        The C Data Forms Library               Page 58     
  3673.  
  3674.        If there are no errors, FormSetOptions() returns NO_ERROR.
  3675.  
  3676.        If there are errors, FormSetOptions() returns one of the
  3677.        following and sets window_error_code to one these values:
  3678.  
  3679.        UNDEFINED_FORM if the form does not exist.
  3680.  
  3681.        INVALID_FIELD_OPTION if FORM_VIRTUAL or FORM_HIGHLIGHT is used as
  3682.        an option.
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.  
  3722.  
  3723.  
  3724.  
  3725.  
  3726.  
  3727.  
  3728.  
  3729.  
  3730.  
  3731.  
  3732.          Page 59        The C Data Forms Library               Page 59     
  3733.  
  3734.                       WRITING VALUES TO THE FIELD BUFFER
  3735.                       ----------------------------------
  3736.  
  3737.        You can write values to the field buffer as strings and have them
  3738.        displayed immediately.  This will be necessary if you want to
  3739.        change a field's value if the field is not the current field being
  3740.        edited.  The FormWriteFieldValue() function does just this.  This
  3741.        function is an alternative to the FormPutFieldData() function.
  3742.  
  3743.  
  3744.  
  3745.        FormWriteFieldValue()
  3746.        ---------------------
  3747.  
  3748.        The FormWriteFieldValue() writes a string to the field's input
  3749.        buffer and displays the changes immediately.  Here is the
  3750.        prototype:
  3751.  
  3752.        int FormWriteFieldValue(FORMPTR form, int entrynum, char *value)
  3753.  
  3754.        The first and second arguments are the form and the field entry
  3755.        number, respectively.
  3756.  
  3757.        The third argument is the pointer to the string of characters to
  3758.        write to the string buffer.  The length of the string cannot exceed
  3759.        the length of the field's input buffer.  If you do not know the
  3760.        length of the field buffer, you can use the FIELD_BUFSIZE() macro.
  3761.  
  3762.  
  3763.        #include "cwlform.h"
  3764.  
  3765.        main()
  3766.        {
  3767.          /*... Assume initializations are done ... */
  3768.  
  3769.          FormWriteFieldValue(form,1,"45");
  3770.        }
  3771.  
  3772.        This writes a string "45" to the field's input buffer and displays
  3773.        "45" on the form (if the field's position is visible on the
  3774.        screen).
  3775.  
  3776.  
  3777.        If there are no errors, FormWriteFieldValue() returns NO_ERROR.
  3778.  
  3779.        If there are errors, FormWriteFieldValue() returns one of the
  3780.        following and sets window_error_code to one these values:
  3781.  
  3782.        UNDEFINED_FORM if the FORMPTR does not exist.
  3783.  
  3784.        UNDEFINED_FIELD if the field entry does not exist
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.          Page 60        The C Data Forms Library               Page 60     
  3793.  
  3794.                           SETTING FIELD PRE-FUNCTIONS
  3795.                           ---------------------------
  3796.  
  3797.  
  3798.        The C Data Forms Library's form manager allows functions to be
  3799.        called prior to inputting a field.  This function is not limited to
  3800.        just 'call a function and return to inputting' type of a function
  3801.        that you may find in some other commercial or shareware function
  3802.        libraries.  The pre functions in The C Data Forms Library have the
  3803.        added power of telling the form manager what to do next i.e. edit
  3804.        the current field, go to some other field, exit the form, etc.
  3805.  
  3806.        There are two ways of setting up a pre-input function.  One way is
  3807.        to define a global function that will be called for every field in
  3808.        every form defined.  The second way is to define a pre-input
  3809.        function for each individual field in a particular form.
  3810.  
  3811.  
  3812.        Defining a global pre-functions
  3813.        -------------------------------
  3814.  
  3815.        You can define a function that will be performed prior to inputting
  3816.        of every field in any form defined.  The global_field_prefunc
  3817.        function pointer points to this function.  Here is the prototype:
  3818.  
  3819.                int (*global_field_prefunc)(FORMPTR form, int *entrynum)
  3820.  
  3821.        The first argument is the pointer to the current active form.
  3822.  
  3823.        The second argument is a pointer to an integer that represents the
  3824.        current field number being edited.  The reason for a pointer and
  3825.        not the actual value will become apparent later on.
  3826.  
  3827.  
  3828.  
  3829.        Defining a field specific pre-input functions
  3830.        ---------------------------------------------
  3831.  
  3832.        The FormSetFieldPreFunction() defines a pre-input function for a
  3833.        particular field in a form.  Here is the prototype:
  3834.  
  3835.        int FormSetFieldPreFunction(FORMPTR form, int entrynum,
  3836.                                    int (*prefunc)(FORMPTR form, ]
  3837.                                    int *entry))
  3838.  
  3839.        The first argument is the pointer to the form, and the second the
  3840.        field number to assign the function to.
  3841.  
  3842.        The third argument is a pointer to the function that returns an
  3843.        integer.  The arguments to this function are the same as the
  3844.        global_field_prefunc function pointer defined above.
  3845.  
  3846.  
  3847.  
  3848.  
  3849.  
  3850.  
  3851.  
  3852.          Page 61        The C Data Forms Library               Page 61     
  3853.  
  3854.        Return Values to the Form Manager
  3855.        ---------------------------------
  3856.  
  3857.        The global_field_prefunc and the function defined in the
  3858.        FormSetFieldPreFunction() MUST return a value back to the form
  3859.        manager.  This return value tells the form manager what to do next.
  3860.        Here is a list of the valid return values:
  3861.  
  3862.  
  3863.        Option                            Definition
  3864.        ------                            ----------
  3865.  
  3866.        FIELD_PREVFIELD            Move input cursor to the previous field
  3867.                                   in the form and start editing from there.
  3868.  
  3869.        FIELD_NEXTFIELD            Move input cursor to the next field in
  3870.                                   the form and continue editing the next
  3871.                                   field.
  3872.  
  3873.        FIELD_CONTINUE_PROCESS     Edit the input for the current field.
  3874.  
  3875.        FIELD_PROCESS_DATA         Process input that was already entered
  3876.                                   in the field.
  3877.  
  3878.        FORM_CLEAR                 Clear the form and move input cursor to
  3879.                                   first available field.
  3880.  
  3881.        FORM_ACCEPT                Accept the current input in the form and
  3882.                                   exit.
  3883.  
  3884.        FIELD_NEWFIELD             Move cursor to a new field and continue
  3885.                                   editing from there.
  3886.  
  3887.        FORM_EXIT_CLEAR            Clear the form and quit editing.
  3888.  
  3889.        The FIELD_PREVFIELD return value will move the input cursor to the
  3890.        previous field in the form.  If you try to move beyond the first
  3891.        available field on the form the FORM_WRAP and/or the
  3892.        FORM_EXIT_INITIAL form options will take action depending on
  3893.        whether they are on or off.  See CREATING FIELD ENTRIES for a
  3894.        definition of the FORM_WRAP and FORM_EXIT_INITIAL options.
  3895.  
  3896.        The FIELD_NEXTFIELD return value will move the input cursor to the
  3897.        next field in the form.  If you try to move beyond the first
  3898.        available field in the form, the FORM_WRAP form option will take
  3899.        action depending on whether this option was turned on.
  3900.  
  3901.        The FIELD_CONTINUE_PROCESS return value will just let the form
  3902.        manager edit the current field, just as if the pre-input function
  3903.        was not called.
  3904.  
  3905.        The FIELD_PROCESS_DATA return value will process whatever data is
  3906.        residing the field's input buffer, and will not edit the current
  3907.        field.  You can place strings in the field input buffer by calling
  3908.        the FormWriteFieldValue() function.  The FIELD_PROCESS_DATA will
  3909.        still right or left justify, comma format, etc. whatever is in the
  3910.        field buffer, just as if it were entered manually (edited).
  3911.  
  3912.          Page 62        The C Data Forms Library               Page 62     
  3913.  
  3914.        The FORM_CLEAR return value clears the form of all input data and
  3915.        moves the input cursor to the first available field.
  3916.  
  3917.        The FORM_ACCEPT return value accepts all the input from the input
  3918.        fields and exits.  The form is not exited automatically if the
  3919.        FORM_CHECK option is on or if a field in the form has the
  3920.        FIELD_CHECK option on.  See CREATING FIELD ENTRIES for a definition
  3921.        of the FORM_CHECK and FIELD_CHECK options.
  3922.  
  3923.        The FIELD_NEWFIELD return value moves the input cursor to the field
  3924.        assigned to the pointer to the current entry.  If you remember, the
  3925.        pre-function prototype passed a pointer to the current field
  3926.        number.  If you assign a field number to the dereferenced pointer
  3927.        and the FIELD_NEWFIELD return value is used, the form manager will
  3928.        move the input cursor to the field desired.  If the field entry
  3929.        does not exist, the form manager will not move the input cursor.
  3930.        If the field is protected (FIELD_PROTECT flag is on) for the
  3931.        desired field, the input cursor is not moved.
  3932.  
  3933.        The FORM_EXIT_CLEAR clears the form of all input and exits the
  3934.        form.  The form is not automatically cleared and exited if there is
  3935.        an exit function defined for the form.  Form exit functions are
  3936.        discussed later in the manual.
  3937.  
  3938.        If both the global_field_prefunc and an entry has a pre-input
  3939.        function defined via the FormSetFieldPreFunction() function, the
  3940.        global_field_prefunc is performed first.  If the return value from
  3941.        the global function is FIELD_CONTINUE_PROCESS, then the pre-input
  3942.        function defined for the field is performed.
  3943.  
  3944.        #include "cwlform.h"
  3945.        #include "menu.h"
  3946.  
  3947.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  3948.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  3949.        #define NUMPROMPTS 5
  3950.  
  3951.        FIELD_ENTRY field_array[] =
  3952.        {INTEGER,1,35,"___",'_',1,3,FIELD_RJUSTIFY,1,REVERSE,"3[0-9]",
  3953.         STRING, 2, 35, "__________", '_', 0, 10, NO_FIELD_OPTIONS,
  3954.                 1,REVERSE, "10.",
  3955.         LINTEGER,3, 35, "_________", '_', 2, 12,
  3956.                 FIELD_COMMA|FIELD_ZSUPPRESS2, 1,REVERSE, "9[0-9]",
  3957.         DOUBLE,4, 20, "_______",'_',1,7, FIELD_COMMA|FIELD_LJUSTIFY,1,
  3958.                 REVERSE,"7[0-9/.]",
  3959.         CHAR, 5, 20, "_", '_', 1, 1, FIELD_UPPERCASE, 1,REVERSE,
  3960.                 "[YyNn]",
  3961.        FIELDEND};
  3962.  
  3963.        FORMPTR form;
  3964.        WPOINTER w, helpwin;
  3965.        char *prompt[] = { "Enter an integer:",
  3966.                           "Choose a string:",
  3967.                           "Enter a large integer value:",
  3968.                           "Enter a double:",
  3969.                           "Enter Yes or No (Y/N):"};
  3970.  
  3971.  
  3972.          Page 63        The C Data Forms Library               Page 63     
  3973.  
  3974.        char *help[] =   {"Enter a value between 0 and 999",
  3975.                        "Use Up arrow or down arrow to make selection",
  3976.                        "Enter a value between 0 and 2,000,000",
  3977.                        "Enter a value with a decimal point",
  3978.                        "Enter a 'Y' for yes, 'N' for no"};
  3979.  
  3980.        int display_help();
  3981.        int get_choice();
  3982.        int choose_list();
  3983.  
  3984.        POPUP_MENU_ENTRY popup_entry[] = {"Choice 1",1,0,0,NULLFN,
  3985.                                        "Choice 2",2,0,0,NULLFN,
  3986.                                        "Choice 3",3,0,0,NULLFN,
  3987.                                        "Choice 4",4,0,0,NULLFN,
  3988.                                        "Choice 5",5,0,0,NULLFN,
  3989.                                        "Choice 6",6,0,0,NULLFN,
  3990.                                        "Choice 7",7,0,0,NULLFN,
  3991.                                        CWL_NULL,0};
  3992.        POPUP_MENU_PTR popup;
  3993.        unsigned menu_colors[NUMPOPUPCOLORS];
  3994.        main()
  3995.        {
  3996.          int i;
  3997.          WindowInitializeSystem();
  3998.          FormInitializeSystem();
  3999.          FormInitializeFloat();
  4000.          WindowSaveInitial(0);
  4001.  
  4002.          menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  4003.          menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  4004.          menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
  4005.          menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
  4006.          menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
  4007.  
  4008.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  4009.          WindowOpen(w);
  4010.  
  4011.          /* write prompts to the form window */
  4012.          for (i=0;i<NUMPROMPTS;i++)
  4013.            WindowWriteString(w,prompt[i],i+1,1);
  4014.  
  4015.          /* setup help window */
  4016.          helpwin = WindowInitialize(NOBORDER,25,1,78,1,REVERSE,REVERSE,0);
  4017.          WindowOpen(helpwin);
  4018.          popup = PopupCreateMenu(popup_entry,menu_colors,4,10,7,
  4019.                                  NO_POPUP_OPTIONS,WNULLFN,VWNULLFN);
  4020.          /* initialize form */
  4021.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  4022.  
  4023.          FormSetListField(form,2,popup);
  4024.  
  4025.          /* set field pre-func of second field */
  4026.          FormSetFieldPreFunction(form,2,get_choice);
  4027.  
  4028.          /* display help window */
  4029.          WindowDisplay(helpwin, 2, NOEFFECT);
  4030.  
  4031.  
  4032.          Page 64        The C Data Forms Library               Page 64     
  4033.  
  4034.          /* get form info */
  4035.          FormGetInput(form,1,1);
  4036.        }
  4037.  
  4038.        /* Displays help for each field */
  4039.        int display_help(FORMPTR form, int *entry)
  4040.        {
  4041.          /* clear window and display appropriate help */
  4042.          WindowClear(helpwin);
  4043.          WindowWriteString(helpwin,help[*entry-1],1,1);
  4044.  
  4045.          /* return value back to form manager */
  4046.          return FIELD_CONTINUE_PROCESS;
  4047.        }
  4048.  
  4049.  
  4050.        The above example displays a help message for each input field.
  4051.        Note that the display_help() function returns a
  4052.        FIELD_CONTINUE_PROCESS to the form manager.
  4053.  
  4054.        If there are no errors, FormSetFieldPreFunction() returns NO_ERROR.
  4055.  
  4056.        If there are errors, FormSetFieldPreFunction() returns one of the
  4057.        following and sets window_error_code to one these values:
  4058.  
  4059.        UNDEFINED_FORM if the FORMPTR does not exist.
  4060.  
  4061.        UNDEFINED_FIELD if the field entry does not exist
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.          Page 65        The C Data Forms Library               Page 65     
  4093.  
  4094.                          SETTING FIELD POST FUNCTIONS
  4095.                          ----------------------------
  4096.  
  4097.  
  4098.        The C Data Forms Library's form manager allows functions to be
  4099.        called after inputting a field.
  4100.  
  4101.        There are two ways of setting up a post-input function.  One way is
  4102.        to define a global function that will be called for every field in
  4103.        every form defined.  The second way is to define a post-input
  4104.        function for each individual field in a particular the form.
  4105.  
  4106.  
  4107.        Defining a global post-function
  4108.        -------------------------------
  4109.  
  4110.        You can define a function that will be performed prior to inputting
  4111.        of every field in any form defined.  The global_field_postfunc
  4112.        function pointer points to this function.  Here is the prototype:
  4113.  
  4114.                int (*global_field_postfunc)(FORMPTR form, int *entrynum)
  4115.  
  4116.        The first argument is the pointer to the current active form.
  4117.  
  4118.        The second argument is a pointer to an integer that represents the
  4119.        current field number being edited.  The reason for a pointer and
  4120.        not the actual value will become apparent later on.
  4121.  
  4122.  
  4123.        Defining a field specific post-function
  4124.        ---------------------------------------
  4125.  
  4126.        The FormSetFieldPostFunction() defines a post-input function for a
  4127.        particular field in a form.  Here is the prototype:
  4128.  
  4129.        int FormSetFieldPostFunction(FORMPTR form, int entrynum,
  4130.                           int (*postfunc)(FORMPTR form, int *entry))
  4131.  
  4132.        The first argument is the pointer to the form, and the second the
  4133.        field number to assign the function to.
  4134.  
  4135.        The third argument is a pointer to the function that returns an
  4136.        integer.  The arguments to this function are the same as the
  4137.        global_field_postfunc function pointer defined above.
  4138.  
  4139.  
  4140.        Return Values to the Form Manager
  4141.        ---------------------------------
  4142.  
  4143.        The global_field_postfunc and the function defined in the
  4144.        FormSetFieldPostFunction() MUST return a value back to the form
  4145.        manager.  This return value tells the form manager what to do next.
  4146.        Here is a list of the valid return values:
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.          Page 66        The C Data Forms Library               Page 66     
  4153.  
  4154.        Option                            Definition
  4155.        ------                            ----------
  4156.  
  4157.        FIELD_PREVFIELD            Move input cursor to the previous field
  4158.                                   in the form and start editing from there.
  4159.  
  4160.        FIELD_NEXTFIELD            Move input cursor to the next field in
  4161.                                   the form and continue editing the next
  4162.                                   field.
  4163.  
  4164.        FIELD_CONTINUE_PROCESS     Continue processing the field (display
  4165.                                   value entered in field buffer from
  4166.                                   previous edit).
  4167.  
  4168.        FIELD_PROCESS_DATA         Same as FIELD_CONTINUE_PROCESS.
  4169.  
  4170.        FORM_CLEAR                 Clear the form and move input cursor to
  4171.                                   first available field.
  4172.  
  4173.        FORM_ACCEPT                Accept the current input in the form and
  4174.                                   exit.
  4175.  
  4176.        FIELD_NEWFIELD             Move cursor to a new field and continue
  4177.                                   editing from there.
  4178.  
  4179.        FORM_EXIT_CLEAR            Clear the form and quit editing.
  4180.  
  4181.        The above return values are the same as the return values for
  4182.        pre-input function except for the FIELD_CONTINUE_PROCESS and
  4183.        FIELD_PROCESS_DATA functions.  FIELD_CONTINUE_PROCESS just
  4184.        continues as if no post-input function was called.
  4185.        FIELD_PROCESS_DATA has the same definition as
  4186.        FIELD_CONTINUE_PROCESS.
  4187.  
  4188.        If both the global_field_postfunc and an entry has a post-input
  4189.        function defined via the FormSetFieldPostFunction() function, the
  4190.        global_field_postfunc is performed first.  If the return value from
  4191.        the global function is FIELD_CONTINUE_PROCESS, then the post-input
  4192.        function defined for the field is performed.
  4193.  
  4194.        Here is an example of using the post-input functions:
  4195.  
  4196.        #include <stdio.h>
  4197.        #include "cwlform.h"
  4198.  
  4199.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  4200.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  4201.        #define NUMPROMPTS 3
  4202.  
  4203.        FIELD_ENTRY field_array[] =
  4204.        {INTEGER,1,35,"___",'_',1,3,FIELD_RJUSTIFY,1,REVERSE,"3[0-9]",
  4205.        INTEGER,2,35,"___",'_',1,3,FIELD_RJUSTIFY,1,REVERSE,"3[0-9]",
  4206.        INTEGER,3,35,"___",'_',1,3,FIELD_RJUSTIFY,1,REVERSE,"3[0-9]",
  4207.        INTEGER,4,35,"___",'_',1,3,FIELD_RJUSTIFY,1,REVERSE,"3[0-9]",
  4208.        INTEGER,5,35,"____",'_',1,4,FIELD_RJUSTIFY|FIELD_PROTECT,1,
  4209.                          REVERSE,"4[0-9]",
  4210.        FIELDEND};
  4211.  
  4212.          Page 67        The C Data Forms Library               Page 67     
  4213.  
  4214.        FORMPTR form;
  4215.        WPOINTER w, helpwin;
  4216.  
  4217.        char *prompt = "Enter a number between 0 and 999:";
  4218.        char *totstr = "Current Total :";
  4219.        int display_total();
  4220.        main()
  4221.        {
  4222.          int i;
  4223.          WindowInitializeSystem();
  4224.          FormInitializeSystem();
  4225.          WindowSaveInitial(0);
  4226.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  4227.          WindowOpen(w);
  4228.  
  4229.          /* write prompts to the form window */
  4230.          for (i=0;i<=NUMPROMPTS;i++)
  4231.          WindowWriteString(w,prompt,i+1,1);
  4232.          WindowWriteString(w,totstr,5,1);
  4233.  
  4234.          /* initialize form */
  4235.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  4236.  
  4237.          /* set global post-function */
  4238.          global_field_postfunc = display_total;
  4239.  
  4240.          /* get form info */
  4241.          FormGetInput(form,1,1);
  4242.        }
  4243.  
  4244.        /* call total function */
  4245.        int display_total(FORMPTR form, int *entry)
  4246.        {
  4247.          int i,total=0,num;
  4248.          for (i=1;i<=4;i++)
  4249.          {
  4250.            FormGetFieldData(form,i,&num);
  4251.            total+=num;
  4252.          }
  4253.          FormPutFieldData(form,5,total);
  4254.          return FIELD_CONTINUE_PROCESS;
  4255.        }
  4256.  
  4257.        The above example displays a running total of four input fields.
  4258.        The total is displayed in the fifth input field.  Note the return
  4259.        value of FIELD_CONTINUE_PROCESS, which informs the form manager to
  4260.        carry on as if no post-input function had been call.
  4261.  
  4262.        If there are no errors, FormSetFieldPostFunction() returns
  4263.        NO_ERROR.
  4264.  
  4265.        If there are errors, FormSetFieldPostFunction() returns one of the
  4266.        following and sets window_error_code to one these values:
  4267.  
  4268.        UNDEFINED_FORM if the FORMPTR does not exist.
  4269.  
  4270.        UNDEFINED_FIELD if the field entry does not exist.
  4271.  
  4272.          Page 68        The C Data Forms Library               Page 68     
  4273.  
  4274.                      UNDEFINED KEYSTROKE PROCESSING
  4275.                      ------------------------------
  4276.  
  4277.        Another powerful feature of the form library is that you can call a
  4278.        function for keys that are not in the current key definitions.  For
  4279.        instance, say you want the Tab key and the down arrow to mean
  4280.        accept the input and go to the next field.  Since there is only
  4281.        room for one definition for accept input, you can write a function
  4282.        that checks for the Tab key, and return a value to the form manager
  4283.        as to what action to take.
  4284.  
  4285.  
  4286.        The form_undef_fkey_func and form_undef_akey_func function pointers
  4287.        -------------------------------------------------------------------
  4288.  
  4289.        There are two global variables, form_undef_fkey_func and
  4290.        form_undef_akey_func.  These two variables are pointers to
  4291.        functions that return an integer.  By setting these functions to
  4292.        point to your own functions, you can process undefined keystrokes
  4293.        yourself and return to the form manager what action to take.
  4294.  
  4295.        The form_undef_fkey_func is used to define keys that are not normal
  4296.        ASCII keys.  For instance, Control key and Alt key combinations,
  4297.        the F-keys, PgDn and PgUp, etc.  The form_undef_akey_func is used
  4298.        to define normal ASCII keys (keys with ASCII values between 32 and
  4299.        255, inclusive).
  4300.  
  4301.        Whenever an undefined key is encountered, the form manager will
  4302.        pass the current FORMPTR, current field entry (as an integer), the
  4303.        string that has been currently entered, the current key pressed,
  4304.        and the current position number of the character being processed to
  4305.        your function.  The prototype for this function is as follows:
  4306.  
  4307.        int (*form_undef_fkey_func)(FORMPTR form, /* current form */
  4308.                                    int entry,     /* current field */
  4309.                                    char *str,/* string currently entered */
  4310.                                    int key,  /* key that was pressed */
  4311.                                    int *pos) /* position number of current
  4312.                                              character being processed */
  4313.  
  4314.        The prototype to the form_undef_akey_func is similar to the one
  4315.        above.  The str is a pointer to a null-terminated string of
  4316.        characters that has been currently entered.  For instance, if the
  4317.        string currently entered is
  4318.  
  4319.                ABC123
  4320.  
  4321.        str will point to "ABC123".  The key value is the key that was
  4322.        pressed.  You should use the values defined in the header file
  4323.        "keycodes.h" if you want to check for non-ascii keys.  This will
  4324.        ensure that you are properly checking the keystroke desired.  For
  4325.        instance, if you want to check if the key pressed was the Page Up
  4326.        key, use the constant PGUP defined in keycodes.h.
  4327.  
  4328.  
  4329.        The pos argument is a pointer to an integer that denotes the number
  4330.        of the current character that the cursor is on.  The first
  4331.  
  4332.          Page 69        The C Data Forms Library               Page 69     
  4333.  
  4334.        character is at position number 0, the second character in the
  4335.        input field is 1, etc.  If there is an input mask the position
  4336.        number does not include any characters that are used to create the
  4337.        non-input positions.  For instance:
  4338.  
  4339.                        "__/__/__ "
  4340.                         01 23 45
  4341.        The numbers under the mask are the position numbers for each
  4342.        character.  The reason why the pos argument is a pointer, and not a
  4343.        regular integer will be defined later.
  4344.  
  4345.  
  4346.        Specifying when to call an undefined key function in a Regular
  4347.        Expression
  4348.        ----------
  4349.  
  4350.        An empty bracketed simple regular expression tells the form manager
  4351.        to call the undefined keystroke function.  An example of this type
  4352.        of regular expression is as follows:
  4353.  
  4354.                Regular                  Definition
  4355.                Expression                 ----------
  4356.                ----------
  4357.  
  4358.               [A-Z][]                  The first input position must be
  4359.                                        between 'A' and 'Z', and the second
  4360.                                        position will automatically call
  4361.                                        the user defined undefined
  4362.                                        keystroke function.
  4363.  
  4364.               20[]                     All twenty input positions will
  4365.                                        call the undefined keystroke
  4366.                                        function.
  4367.  
  4368.               3[0-9]2[]2[A-Z]          The first three input positions
  4369.                                        must be between '0' and '9', the
  4370.                                        next two input positions
  4371.                                        automatically call the undefined
  4372.                                        keystroke function, and the last two
  4373.                                        positions must be between 'A' and 'Z'.
  4374.  
  4375.  
  4376.        If you use this form of a regular expression, you MUST have defined
  4377.        an undefined keystroke function.  If you did not define one, you
  4378.        will more than likely get into an infinite loop.  Using this form
  4379.        of regular expression combined with the return values (defined
  4380.        below) that can be returned to the input manager, you will
  4381.        virtually have total control of the way the input is handled.
  4382.  
  4383.  
  4384.        Return Values To The Form Manager
  4385.        ---------------------------------
  4386.  
  4387.        When writing your function you must return an integer to the form
  4388.        manager.  This integer will inform the form manager as to what
  4389.        action to take.  Here are a list of the return values and what they
  4390.        inform the form manager:
  4391.  
  4392.          Page 70        The C Data Forms Library               Page 70     
  4393.  
  4394.        Return                         Action to
  4395.        Value                            Take
  4396.        ------                         ---------
  4397.  
  4398.        FIELD_CONTINUE          Do not Process keystroke and continue
  4399.                                getting input.
  4400.  
  4401.        FIELD_MOVELEFT          Move cursor left in field.
  4402.  
  4403.        FIELD_MOVERIGHT         Move cursor right in field.
  4404.  
  4405.        FIELD_DELNOMOVE         Delete character at cursor.
  4406.  
  4407.        FIELD_INSTOGGLE         Toggle Insert/Overwrite mode.
  4408.  
  4409.        FIELD_BACKSPACE         Destructive Backspace.
  4410.  
  4411.        FIELD_ACCEPT            Accept Input and go to next field.
  4412.  
  4413.        FIELD_ACCEPTDEFAULT     Accept default field string and return.
  4414.  
  4415.        FIELD_ERASEINPUT        Erase Input and go to first character in
  4416.                                the field.
  4417.  
  4418.        FIELD_GOTOFIRST         Go to first input character in field.
  4419.  
  4420.        FIELD_GOTOLAST          Move cursor to last input character in
  4421.                                field.
  4422.  
  4423.        FIELD_INSERTCHAR        Accept character as valid and insert it at
  4424.                                the current cursor position.
  4425.  
  4426.        FIELD_NEXTFIELD         Accept input and go to the next field in
  4427.                                the form.
  4428.  
  4429.        FIELD_PREVFIELD         Accept input and go to the previous field.
  4430.  
  4431.        FORM_ACCEPT             Accept all input in the form and exit form.
  4432.  
  4433.        FORM_CLEAR              Clear the form and move input to first
  4434.                                available field entry.
  4435.  
  4436.        FORM_EXIT_CLEAR         Clear the form and quit editing.
  4437.  
  4438.  
  4439.        FIELD_MOVE_TO_CHARACTER   Move cursor to input position specified
  4440.                                  in the *pos argument.
  4441.  
  4442.        The FIELD_MOVE_TO_CHARACTER return value moves the input cursor to
  4443.        the position in the input string specified in the fourth argument
  4444.        of form_undef_akey_func or form_undef_fkey_func.  If you recall,
  4445.        the fourth argument was a pointer to an integer.  You can assign a
  4446.        value to the *pos argument in your user defined function, and then
  4447.        return a FIELD_MOVE_TO_CHARACTER return code to move the input
  4448.        cursor to the desired input position.
  4449.  
  4450.  
  4451.  
  4452.          Page 71        The C Data Forms Library               Page 71     
  4453.  
  4454.        These user-defined functions can do anything, not just process
  4455.        keystrokes.  For instance, if you want F1 to be a help key, where
  4456.        the help function is in a function called do_help() you must make
  4457.        sure that:
  4458.  
  4459.  
  4460.        a) the F1 key is undefined (not defined in the form_edit_key array)
  4461.        b) the form_undef_fkey_func function pointer points to your
  4462.           function c) return an integer to the form manager from your
  4463.           function.
  4464.  
  4465.        Here is a typical way that this would be set up:
  4466.  
  4467.  
  4468.        #include "window.h"
  4469.  
  4470.        /*  ... Other #includes and #defines */
  4471.  
  4472.        int do_help();           /* define help function */
  4473.  
  4474.        main()
  4475.        {
  4476.          WindowInitializeSystem();
  4477.          FormInitializeSystem();
  4478.          /* ...Some code */
  4479.          form_undef_fkey_func = do_help;   /* point function pointer
  4480.                                               to do_help */
  4481.          FormGetInput(/*  ... Parameters */);    /* call input
  4482.                                                     function */
  4483.  
  4484.          /* ... Other code */
  4485.        }
  4486.  
  4487.  
  4488.        int do_help(FORMPTR form, int entry, char *str, int ch, int pos)
  4489.        {
  4490.          if (ch == F1)                     /* check for F1 */
  4491.          {
  4492.                /* help function goes here */
  4493.  
  4494.          }
  4495.          return FIELD_DONT_PROCESS;  /* make sure form manager does not
  4496.                                        process this or any other undefined
  4497.                                        keystroke */
  4498.        }
  4499.  
  4500.        With this flexibility in the input functions, you can totally
  4501.        control how input is handled.
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.          Page 72        The C Data Forms Library               Page 72     
  4513.  
  4514.                         PROCESSING EDITING ERRORS
  4515.                         -------------------------
  4516.  
  4517.        There are two categories of errors that The C Data Forms Library
  4518.        checks for when editing a field in a form.  The first category
  4519.        includes checking to see if enough characters have been entered
  4520.        into the field and to make sure the input matches the regular
  4521.        expression.
  4522.  
  4523.        The second category are errors that occur when the field is checked
  4524.        to see if the data entered falls in a valid range, the name entered
  4525.        is found in a database of some type, etc. namely the errors that
  4526.        The C Data Forms Library cannot check for internally, only you (the
  4527.        programmer) knows whether the data entered is valid.
  4528.  
  4529.        This section deals with the first category of errors.
  4530.  
  4531.        Minimum Number of Characters Error Checking
  4532.        -------------------------------------------
  4533.  
  4534.        The C Data Forms Library internally checks to see if the number of
  4535.        characters entered manually into a field (not data written to the
  4536.        field using the FormWriteFieldValue() function) is enough to
  4537.        satisfy the minimum number of characters that must be entered for
  4538.        the field.  As stated before, the minimum number of characters
  4539.        expected is initialized in the FIELD_ENTRY structure.
  4540.  
  4541.  
  4542.        Overriding Error Checking for Minimum number of characters
  4543.        ----------------------------------------------------------
  4544.  
  4545.        You can override checking the number of characters entered by
  4546.        turning on one or both of the override options,
  4547.        FIELD_OVERRIDE_FORWARD and FIELD_OVERRIDE_BACKWARD.  The
  4548.        FIELD_OVERRIDE_FORWARD overrides checking when the field is exited
  4549.        with a forward (toward the last field in the form) advance.  The
  4550.        FIELD_OVERRIDE_BACKWARD overrides checking when the field is exited
  4551.        with a backward advance (toward the first field in the form).  As
  4552.        stated in previous sections, FormSetFieldOptions() turns on or
  4553.        turns off field options.  Some useful purposes of overriding the
  4554.        number of characters entered error checking is to allow the user to
  4555.        move to a previous field so that it can be changed, without having
  4556.        to enter some data in the current field.  Here is an example of
  4557.        using this technique with the FIELD_OVERRIDE_BACKWARD option.
  4558.  
  4559.  
  4560.        #include "cwlform.h"
  4561.  
  4562.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  4563.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  4564.        #define NUMPROMPTS 8
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.          Page 73        The C Data Forms Library               Page 73     
  4573.  
  4574.        FIELD_ENTRY field_array[] =
  4575.        {INTEGER,1,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4576.                "3[0-9]",
  4577.         INTEGER,2,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4578.                "3[0-9]",
  4579.        INTEGER,3,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4580.                "3[0-9]",
  4581.        INTEGER,4,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4582.                "3[0-9]",
  4583.        INTEGER,5,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4584.                "3[0-9]",
  4585.        INTEGER,6,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4586.                "3[0-9]",
  4587.        INTEGER,7,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4588.                "3[0-9]",
  4589.        INTEGER,8,35,"___",'_',1,3,FIELD_OVERRIDE_BACKWARD,1,REVERSE,
  4590.                "3[0-9]",
  4591.        FIELDEND};
  4592.  
  4593.        FORMPTR form;
  4594.        WPOINTER w;
  4595.  
  4596.        char *prompt = "Enter a number :";
  4597.  
  4598.        main()
  4599.        {
  4600.          int i;
  4601.          WindowInitializeSystem();
  4602.          FormInitializeSystem();
  4603.          WindowSaveInitial(0);
  4604.  
  4605.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  4606.          WindowOpen(w);
  4607.  
  4608.          /* write prompts to the form window */
  4609.          for (i=0;i<NUMPROMPTS;i++)
  4610.            WindowWriteString(w,prompt,i+1,1);
  4611.  
  4612.          /* initialize form */
  4613.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  4614.  
  4615.          /* get form info */
  4616.          FormGetInput(form,1,1);
  4617.        }
  4618.  
  4619.        The example above allows the user to edit a previous field even
  4620.        though the field may not contain any characters.  The
  4621.        FIELD_OVERRIDE_BACKWARD option allows us to override the minimum
  4622.        number of characters error check.
  4623.  
  4624.  
  4625.  
  4626.        Checking if Field Characters Match Regular Expression
  4627.        -----------------------------------------------------
  4628.  
  4629.        Another check that is done internally is to see if each character
  4630.        entered matches the corresponding regular expression character.
  4631.  
  4632.          Page 74        The C Data Forms Library               Page 74     
  4633.  
  4634.        This check is only done automatically if the FIELD_CHECKREGEXP or
  4635.        FIELD_CHECKREGEXP_IGNORECASE options are turned on.  The way these
  4636.        two options work are exactly the same as the CHECKREGEXP and
  4637.        CHECKREGEXP_IGNORECASE options work for single input fields in the
  4638.        WindowGet...() family of functions.  See page XX for more details
  4639.        on these options.
  4640.  
  4641.  
  4642.        Calling a User Written Function when errors occur
  4643.        -------------------------------------------------
  4644.  
  4645.        You can set up a function that will be called if any of the fields
  4646.        fail the minimum number of entered characters test or the regular
  4647.        expression error test by pointing the field_edit_error_func
  4648.        function pointer to a user-written function.  Here is the prototype
  4649.        to this function pointer:
  4650.  
  4651.        int (*field_edit_error_func)(FORMPTR form, int entrynum,
  4652.                                     int errtype, char *str, int errval)
  4653.  
  4654.        The first argument is a pointer to the form of where the error
  4655.        occurred.
  4656.  
  4657.        The second argument is the number of the offending field entry.
  4658.  
  4659.        The third argument is the type of error that occurred.  If the
  4660.        error occurred because the minimum number of characters were not
  4661.        entered, this value is the constant FIELD_MINCHARS_ERROR.  If the
  4662.        error was caused because the input conflicts with the regular
  4663.        expression, this value is the constant FIELD_REGEXP_ERROR.
  4664.  
  4665.        The fourth argument is the string that was entered in the field.
  4666.  
  4667.        The fifth argument depends on the type of error.  If the error is a
  4668.        FIELD_MINCHARS_ERROR error, this value is the minimum number of
  4669.        characters expected.  If the error is a FIELD_REGEXP_ERROR error
  4670.        this value is the position in string that does not match the
  4671.        regular expression.  Position numbers in the string start from 0.
  4672.  
  4673.  
  4674.        Return Values for User Written Function
  4675.        ---------------------------------------
  4676.  
  4677.        You MUST return a value back to the form manager if your
  4678.        user-defined error function is called.  There are two possible
  4679.        return values, FIELD_ERROR and FIELD_ACCEPT.  FIELD_ERROR tells the
  4680.        form manager to edit the field again i.e. let the user correct
  4681.        his/her error.  The FIELD_ACCEPT return value accepts the input,
  4682.        even though there is an error.
  4683.  
  4684.        Here is an example:
  4685.  
  4686.        #include <stdio.h>
  4687.        #include "cwlform.h"
  4688.  
  4689.  
  4690.  
  4691.  
  4692.          Page 75        The C Data Forms Library               Page 75     
  4693.  
  4694.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  4695.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  4696.        #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_)
  4697.        #define NUMPROMPTS 8
  4698.  
  4699.        FIELD_ENTRY field_array[] =
  4700.        {INTEGER,1,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4701.        INTEGER,2,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4702.        INTEGER,3,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4703.        INTEGER,4,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4704.        INTEGER,5,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4705.        INTEGER,6,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4706.        INTEGER,7,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4707.        INTEGER,8,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4708.        FIELDEND};
  4709.  
  4710.        FORMPTR form;
  4711.        WPOINTER w, error_win;
  4712.  
  4713.        char *prompt = "Enter a number :";
  4714.  
  4715.        int display_error();
  4716.  
  4717.        main()
  4718.        {
  4719.          int i;
  4720.          WindowInitializeSystem();
  4721.          FormInitializeSystem();
  4722.          WindowSaveInitial(0);
  4723.  
  4724.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  4725.          WindowOpen(w);
  4726.  
  4727.          error_win =
  4728.          WindowInitialize(BORDER,1,1,78,22,WHITEONRED,WHITEONRED,
  4729.                           SINGLEBOX);
  4730.          WindowOpen(error_win);
  4731.  
  4732.          /* write prompts to the form window */
  4733.          for (i=0;i<NUMPROMPTS;i++)
  4734.          WindowWriteString(w,prompt,i+1,1);
  4735.  
  4736.          /* initialize form */
  4737.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  4738.  
  4739.          /* initialize error function */
  4740.          field_edit_error_func = display_error;
  4741.  
  4742.          /* get form info */
  4743.          FormGetInput(form,1,1);
  4744.        }
  4745.  
  4746.  
  4747.  
  4748.  
  4749.  
  4750.  
  4751.  
  4752.          Page 76        The C Data Forms Library               Page 76     
  4753.  
  4754.        /* This is called if there is an editing error */
  4755.        int display_error(FORMPTR form, int entry, int errval,
  4756.                          char *str, int pos)
  4757.        {
  4758.          char buf[80];
  4759.          WindowClear(error_win);
  4760.          switch (errval)
  4761.          {
  4762.            case FIELD_MINCHARS_ERROR:  /* not enough characters */
  4763.              sprintf(buf,
  4764.              "You must enter at least %d characters in this field",pos);
  4765.            break;
  4766.  
  4767.            case FIELD_REGEXP_ERROR:    /* regular expression error */
  4768.              sprintf(buf,"Invalid character entered in position %d",pos);
  4769.            break;
  4770.  
  4771.          }
  4772.  
  4773.          /* display window and return to form manager */
  4774.  
  4775.          WindowWriteCenterString(w,buf,3);
  4776.          WindowWriteCenterString(error_win,
  4777.                "Press Any Key to Continue...",5);
  4778.          WindowDisplay(error_win,1,EXPLODE);
  4779.          MakeSound(300,500);
  4780.          GET_KEY();
  4781.          WindowHide(error_window,CONTRACT);
  4782.          return FIELD_ERROR;
  4783.        }
  4784.  
  4785.  
  4786.        If the field_edit_error_func points to a NULLFN, no function is
  4787.        called.
  4788.  
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.  
  4795.  
  4796.  
  4797.  
  4798.  
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.          Page 77        The C Data Forms Library               Page 77     
  4813.  
  4814.                           USER DEFINED ERROR CHECKING
  4815.                           ---------------------------
  4816.  
  4817.        This section discusses the way to have a user-defined error
  4818.        checking function.  This function checks errors that The C Data
  4819.        Forms Library could not possibly do internally.  This includes
  4820.        checking the input for valid names, passwords, etc.
  4821.  
  4822.        The FormSetFieldValidateFunction() function
  4823.        -------------------------------------------
  4824.  
  4825.        The FormSetFieldValidateFunction() allows the programmer to assign
  4826.        a validation function to a field.  Here is the prototype:
  4827.  
  4828.        int FormSetFieldValidateFunction(FORMPTR form, int entrynum,
  4829.                                                int (*func)(FORMPTR cform,
  4830.                                                        int centry,
  4831.                                                        char *str))
  4832.  
  4833.        The first argument is the pointer to a form.  The second argument
  4834.        is the entry number to assign the function to.
  4835.  
  4836.        The third argument is a pointer to the user-defined function.  This
  4837.        function should allow three arguments.  The first and second are
  4838.        the pointer to the form, and the field entry number.  The last
  4839.        argument is the string entered in the field.
  4840.  
  4841.  
  4842.  
  4843.        Return Values for the user defined error function
  4844.        -------------------------------------------------
  4845.  
  4846.        You MUST return a value back to the form manager if your
  4847.        user-defined validation function is called.  There are two possible
  4848.        return values, FIELD_ERROR and FIELD_ACCEPT.  FIELD_ERROR tells the
  4849.        form manager that there was an error, and to edit the field again
  4850.        i.e. let the user correct his/her error.  The FIELD_ACCEPT return
  4851.        value accepts the input as valid.
  4852.  
  4853.        #include <stdio.h>
  4854.        #include "cwlform.h"
  4855.  
  4856.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  4857.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  4858.        #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_)
  4859.        #define NUMPROMPTS 8
  4860.        FIELD_ENTRY field_array[] =
  4861.        {INTEGER,1,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4862.        INTEGER,2,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4863.        INTEGER,3,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4864.        INTEGER,4,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4865.        INTEGER,5,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4866.        INTEGER,6,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4867.        INTEGER,7,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4868.        INTEGER,8,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  4869.        FIELDEND};
  4870.  
  4871.  
  4872.          Page 78        The C Data Forms Library               Page 78     
  4873.  
  4874.        FORMPTR form;
  4875.        WPOINTER w, error_win;
  4876.  
  4877.        char *prompt = "Enter a number :";
  4878.  
  4879.        int display_error();
  4880.  
  4881.        main()
  4882.        {
  4883.          int i;
  4884.          WindowInitializeSystem();
  4885.          FormInitializeSystem();
  4886.          WindowSaveInitial(0);
  4887.  
  4888.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  4889.          WindowOpen(w);
  4890.  
  4891.          error_win =
  4892.          WindowInitialize(BORDER,10,1,78,8,WHITEONRED,WHITEONRED,
  4893.                           SINGLEBOX);
  4894.          WindowOpen(error_win);
  4895.  
  4896.          /* write prompts to the form window */
  4897.          for (i=0;i<NUMPROMPTS;i++)
  4898.            WindowWriteString(w,prompt,i+1,1);
  4899.  
  4900.          /* initialize form */
  4901.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  4902.  
  4903.          /* initialize validation function */
  4904.          for (i=1;i<=NUMPROMPTS;i++)
  4905.            FormSetFieldValidateFunction(form,i,check_range);
  4906.  
  4907.          /* get form info */
  4908.          FormGetInput(form,1,1);
  4909.        }
  4910.  
  4911.  
  4912.        /* This is called to check the range */
  4913.  
  4914.        int check_range(FORMPTR form, int entry, char *str)
  4915.        {
  4916.          int num;
  4917.          WindowClear(error_win);
  4918.          num = atoi(str);
  4919.  
  4920.          /* check and display error window if out of range */
  4921.          if (num < 1 || num > 500)
  4922.          {
  4923.            WindowPrintf(error_win,
  4924.                    "The number entered %s, must be between %d and %d",
  4925.                         str,LOWLIM,HILIM);
  4926.            WindowWriteCenterString(error_win,
  4927.                    "Press Any Key to Continue...",5);
  4928.            WindowDisplay(error_win,1,EXPLODE);
  4929.            MakeSound(300,500);
  4930.  
  4931.  
  4932.          Page 79        The C Data Forms Library               Page 79     
  4933.  
  4934.            GET_KEY();
  4935.            WindowHide(error_win,CONTRACT);
  4936.            /* re-edit this field */
  4937.            return FIELD_ERROR;
  4938.          }
  4939.          else
  4940.          /* field OK */
  4941.            return FIELD_ACCEPT;
  4942.        }
  4943.  
  4944.  
  4945.        The above example tests each field to make sure the input falls
  4946.        between 1 and 500.  If not, an error window is displayed and
  4947.        FIELD_ERROR is returned to the form manager.  If the field is in
  4948.        range, FIELD_ACCEPT is returned to the form manager.
  4949.  
  4950.        There is a better way to check if a field is included in a range of
  4951.        values.  This will be discussed later in the FormCheckFieldRange()
  4952.        function.
  4953.  
  4954.        If there are no errors, FormSetFieldValidateFunction() returns
  4955.        NO_ERROR.
  4956.  
  4957.        If there are errors, FormSetFieldValidateFunction() returns one of
  4958.        the following and sets window_error_code to one these values:
  4959.  
  4960.        UNDEFINED_FORM if the FORMPTR does not exist.
  4961.  
  4962.        UNDEFINED_FIELD if the field entry does not exist
  4963.  
  4964.  
  4965.  
  4966.        FormCheckFieldRange()
  4967.        ---------------------
  4968.  
  4969.        The FormCheckFieldRange() checks if a field's input falls within
  4970.        the range of two values.  These values can be any data type, except
  4971.        doubles (doubles are handled with a separate function).
  4972.  
  4973.        Here is the prototype:
  4974.  
  4975.                int FormCheckFieldRange(FORMPTR form, int entrynum, int
  4976.                                        options, ...)
  4977.  
  4978.        Note the last argument.  The prototype suggests that the argument
  4979.        is optional, but not really.  The '...' means that there are two
  4980.        values expected.  The first value is the lower limit, and the
  4981.        second value is the upper limit.  These values can be of any simple
  4982.        data type, (char, int, unsigned, etc.) as well as two string.
  4983.  
  4984.        The first two arguments are the pointer to the form and the field
  4985.        entry number, respectively.  The third arguments are range options
  4986.        to use.  Here are the list of range options:
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.          Page 80        The C Data Forms Library               Page 80     
  4993.  
  4994.         Range Option                  Definition
  4995.         ------------                  ----------
  4996.         INCLUDE_LOW             Includes the lower limit as valid.
  4997.         INCLUDE_HIGH            Includes the upper limit as valid.
  4998.         EXCLUDE_LOW             Excludes the lower limit as valid.
  4999.         EXCLUDE_HIGH            Excludes the upper limit as valid.
  5000.         NO_RANGE_OPT            No range options (use default).
  5001.  
  5002.        INCLUDE_LOW includes the lower limit in the range check as being a
  5003.        valid number.
  5004.  
  5005.        INCLUDE_HIGH includes the upper limit in the range check as being a
  5006.        valid number.
  5007.  
  5008.        EXCLUDE_LOW does not accept any value that is equivalent to the
  5009.        lower limit.
  5010.  
  5011.        EXCLUDE_HIGH does not accept any value that is equivalent to the
  5012.        upper limit.
  5013.  
  5014.        NO_RANGE_OPT uses the default (INCLUDE_LOW | INCLUDE_HIGH).
  5015.  
  5016.        Note that the bitwise OR (|) can be used to combine options.
  5017.        INCLUDE...  options override EXCLUDE... options if they are both
  5018.        used simultaneously.
  5019.  
  5020.        Here are a few examples of using FormCheckFieldRange():
  5021.  
  5022.        a)  FormCheckFieldRange(form,1,NO_RANGE_OPT,100,200)
  5023.  
  5024.        b)  FormCheckFieldRange(form,1,NO_RANGE_OPT,-1, 50)
  5025.  
  5026.        c)  FormCheckFieldRange(form,3,EXCLUDE_LOW,'a','z')
  5027.  
  5028.        d)  FormCheckFieldRange(form,2,NO_RANGE_OPT,"abc","def");
  5029.  
  5030.  
  5031.        a) Tests if the value entered in field 1 is between 100 and 200,
  5032.           inclusive.
  5033.        b) Tests if the value entered in field 1 is between -1 and 50,
  5034.           inclusive.
  5035.        c) Tests if the single value entered in field 1 is
  5036.           between 'a' and 'z', but not including 'a'.
  5037.        d) Tests if the string entered is between "abc" and "def"
  5038.           inclusive.
  5039.  
  5040.        When the test is made, a value is returned that tells how the test
  5041.        turned out.
  5042.  
  5043.        Value returned                    Definition
  5044.        --------------                    ----------
  5045.  
  5046.        FIELD_LOW                      Field value is too small.
  5047.        FIELD_HIGH                     Field value is too large.
  5048.        FIELD_OUT_OF_RANGE             Field is either too small or too
  5049.                                       large.
  5050.        FIELD_OK Field is in range.
  5051.  
  5052.          Page 81        The C Data Forms Library               Page 81     
  5053.  
  5054.        If there are no errors, FormCheckFieldRange() returns one of the
  5055.        values above.
  5056.  
  5057.        If there are errors other than the ones mentioned above,
  5058.        FormCheckFieldRange() returns one of the following and sets
  5059.        window_error_code to one these values:
  5060.  
  5061.        UNDEFINED_FORM if the FORMPTR does not exist.
  5062.  
  5063.        UNDEFINED_FIELD if the field entry does not exist
  5064.  
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.  
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.          Page 82        The C Data Forms Library               Page 82     
  5113.  
  5114.                              CLEARING A FORM
  5115.                              ---------------
  5116.  
  5117.        FormClear()
  5118.        -----------
  5119.  
  5120.        You can clear a form of all input and move the input cursor to any
  5121.        field using the FormClear() function.  Here is the prototype:
  5122.  
  5123.                int FormClear(FORMPTR form, int entry)
  5124.  
  5125.        The first argument is the pointer to the form, and the second
  5126.        argument is the entry to place the input cursor when the form is
  5127.        cleared.  If the entry is protected, the form manager tries to find
  5128.        the next available field.  The number of characters that is cleared
  5129.        is determined by the visible width of the input field.
  5130.  
  5131.  
  5132.  
  5133.        If there is no error, FormClear() returns NO_ERROR.
  5134.  
  5135.        If there are errors FormClear() returns the following and sets
  5136.        window_error_code to this value:
  5137.  
  5138.        UNDEFINED_FORM if the FORMPTR does not exist.
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.  
  5162.  
  5163.  
  5164.  
  5165.  
  5166.  
  5167.  
  5168.  
  5169.  
  5170.  
  5171.  
  5172.          Page 83        The C Data Forms Library               Page 83     
  5173.  
  5174.                                 EXITING A FORM
  5175.                                 --------------
  5176.  
  5177.        When the last input field is edited, or the form is exited
  5178.        prematurely, an exit function can be called before the form is
  5179.        actually closed.
  5180.  
  5181.        FormSetExitFunction()
  5182.        ---------------------
  5183.  
  5184.        The FormSetExitFunction() sets up a function that will be called
  5185.        whenever a form is exited.  Here is the prototype:
  5186.  
  5187.  
  5188.        int FormSetExitFunction (FORMPTR form,
  5189.                                 int (*exit_func)(FORMPTR cform,
  5190.                                                  int status,
  5191.                                                  int *currfield))
  5192.  
  5193.        The first argument is the pointer to the form.  The second argument
  5194.        is the pointer to a user-defined exit function.  This function is
  5195.        passed three arguments from the form manager.
  5196.  
  5197.        The first argument is the current form.  The second argument is a
  5198.        status indicator that tells how the form was exited (last field was
  5199.        exited, first field was exited etc.).  Here are the list of status
  5200.        codes:
  5201.  
  5202.  
  5203.        Status Code                     Definition
  5204.        -----------                     ----------
  5205.  
  5206.        FIRST_FIELD_EXIT                Form was exited by moving the input
  5207.                                        cursor to a field before the first
  5208.                                        available field in a form.
  5209.  
  5210.        LAST_FIELD_EXIT                 Form was exited by moving the input
  5211.                                        cursor to a field after the last
  5212.                                        available field.
  5213.  
  5214.        FORM_END                        Form exited and saved by other means
  5215.                                        i.e. an accept key was hit in the
  5216.                                        middle of the form.
  5217.  
  5218.        FORM_END_CLEAR                  Form exited and potentially cleared
  5219.                                        in the middle of the form.
  5220.  
  5221.        The third argument is a pointer to an entry number.
  5222.        The user-defined exit function MUST return a value back to the form
  5223.        manager.  Here is a list of the valid return values:
  5224.  
  5225.  
  5226.        FORM_ACCEPT - End input of the form.
  5227.        FORM_REEDIT - Reedit the form starting at the entry number assigned
  5228.                      to the pointer *currfield.
  5229.  
  5230.        The FORM_END value ends the processing of the fields.
  5231.  
  5232.          Page 84        The C Data Forms Library               Page 84     
  5233.  
  5234.        The FORM_REEDIT value tells the form manager to collect input again
  5235.        in the form, but start at the number assigned to *currfield.
  5236.  
  5237.        #include <stdio.h>
  5238.        #include "cwlform.h"
  5239.  
  5240.        #define NORM  CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)
  5241.        #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_)
  5242.        #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_)
  5243.        #define NUMPROMPTS 8
  5244.        #define LOWLIM     1
  5245.        #define HILIM      200
  5246.  
  5247.        FIELD_ENTRY field_array[] =
  5248.        {INTEGER,1,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5249.        INTEGER,2,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5250.        INTEGER,3,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5251.        INTEGER,4,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5252.        INTEGER,5,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5253.        INTEGER,6,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5254.        INTEGER,7,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5255.        INTEGER,8,35,"___",'_',1,3,NO_FIELD_OPTIONS,1,REVERSE,"3[0-9]",
  5256.        FIELDEND};
  5257.  
  5258.        FORMPTR form;
  5259.        WPOINTER w, error_win, again_win;
  5260.  
  5261.        char *prompt = "Enter a number :";
  5262.  
  5263.        int check_range();
  5264.        int edit_again();
  5265.  
  5266.        main()
  5267.        {
  5268.          int i;
  5269.          WindowInitializeSystem();
  5270.          FormInitializeSystem();
  5271.          WindowSaveInitial(0);
  5272.  
  5273.          w = WindowInitialize(BORDER,1,1,78,22,NORM,NORM,SINGLEBOX);
  5274.          WindowOpen(w);
  5275.  
  5276.          error_win =
  5277.          WindowInitialize(BORDER,10,1,78,10,WHITEONRED,WHITEONRED,
  5278.                           SINGLEBOX);
  5279.          WindowOpen(error_win);
  5280.  
  5281.          again_win =
  5282.          WindowInitialize(NOBORDER,25,1,80,1,REVERSE,REVERSE,0);
  5283.          WindowOpen(again_win);
  5284.  
  5285.          WindowWriteString(again_win,
  5286.            "Enter a field to edit or ENTER to exit the form",1,1);
  5287.  
  5288.          /* write prompts to the form window */
  5289.          for (i=0;i<NUMPROMPTS;i++)
  5290.            WindowWriteString(w,prompt,i+1,1);
  5291.  
  5292.          Page 85        The C Data Forms Library               Page 85     
  5293.  
  5294.          /* initialize form */
  5295.          form = FormInitialize(w,field_array,FORM_HIGHLIGHT);
  5296.  
  5297.          /* initialize exit function */
  5298.          FormSetExitFunction(form,edit_again);
  5299.  
  5300.          FormSetFieldOptions(form,1,FIELD_PROTECT,1);
  5301.  
  5302.          /* initialize validation function */
  5303.          for (i=1;i<=NUMPROMPTS;i++)
  5304.          FormSetFieldValidateFunction(form,i,check_range);
  5305.  
  5306.          /* get form info */
  5307.          FormGetInput(form,1,1);
  5308.        }
  5309.  
  5310.  
  5311.        /* This is called if there is an editing error */
  5312.  
  5313.        int check_range(FORMPTR form, int entry, char *str)
  5314.        {
  5315.          int num;
  5316.          WindowClear(error_win);
  5317.          num = atoi(str);
  5318.  
  5319.         /* check and display error window if out of range */
  5320.         if (num < LOWLIM || num > HILIM)
  5321.         {
  5322.           WindowPrintf(error_win,"The number entered %s is out of range\n"
  5323.                                  "The number must be between %d and %d",
  5324.                                  str,LOWLIM,HILIM);
  5325.           WindowWriteCenterString(error_win,
  5326.                                   "Press Any Key to Continue...",5);
  5327.           WindowDisplay(error_win,1,EXPLODE);
  5328.           MakeSound(300,500);
  5329.           GET_KEY();
  5330.           WindowHide(error_win,CONTRACT);
  5331.  
  5332.          /* re-edit this field */
  5333.           return FIELD_ERROR;
  5334.         }
  5335.         else
  5336.  
  5337.          /* field OK */
  5338.         return FIELD_ACCEPT;
  5339.        }
  5340.  
  5341.        /* ask user whether they want to re-edit the form */
  5342.        int edit_again(FORMPTR form, int status, int *entry)
  5343.        {
  5344.          char buf[3];
  5345.          int num;
  5346.          buf[0] = 0;
  5347.          WindowDisplay(again_win,1,NOEFFECT);
  5348.  
  5349.  
  5350.  
  5351.  
  5352.          Page 86        The C Data Forms Library               Page 86     
  5353.  
  5354.          /* loop until user has a viable entry or hits return */
  5355.          do
  5356.          {
  5357.            WindowGetString(again_win,1,50,buf,'_',0,2,NO_OPTIONS,1,
  5358.                            "2[0-9]");
  5359.            num = atoi(buf);
  5360.          } while (!((num >= 1 && num <= NUMPROMPTS) || buf[0] == 0));
  5361.          WindowHide(again_win,NOEFFECT);
  5362.  
  5363.          /* return hit, so quit */
  5364.          if (buf[0] == 0)
  5365.          return FORM_END;
  5366.          else
  5367.          {
  5368.            /* assign entry number and return */
  5369.           *entry = num;
  5370.           return FORM_REEDIT;
  5371.          }
  5372.        }
  5373.  
  5374.  
  5375.        The example above makes use of the exit function by asking the user
  5376.        whether he/she wants to edit another field.  If the field number
  5377.        entered is in range, edit_again() returns a FORM_REEDIT to the form
  5378.        manager, as well as assigns the appropriate field number.
  5379.  
  5380.        If the field number that is assigned to *entry is out of bounds,
  5381.        the form manager will always start editing input from the first
  5382.        available field.
  5383.  
  5384.  
  5385.        If there is no error, FormSetExitFunction() returns NO_ERROR.
  5386.  
  5387.        If there are errors FormSetExitFunction() returns the following and
  5388.        sets window_error_code to this value:
  5389.  
  5390.        UNDEFINED_FORM if the FORMPTR does not exist.
  5391.  
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.  
  5409.  
  5410.  
  5411.  
  5412.          Page 87        The C Data Forms Library               Page 87     
  5413.  
  5414.                               DISPOSING OF A FORM
  5415.                               -------------------
  5416.  
  5417.        If a form is no longer needed, all memory allocated to the form
  5418.        should be returned to the heap.
  5419.  
  5420.        FormFree()
  5421.        ----------
  5422.  
  5423.        The FormFree() function deallocates all memory allocated to the
  5424.        form, and makes the FORMPTR invalid.  Here is the prototype:
  5425.  
  5426.                        int FormFree(FORMPTR form)
  5427.  
  5428.        The only argument is the pointer to the form.  Once this function
  5429.        is called, the FORMPTR cannot be used unless it is assigned to a
  5430.        valid form.
  5431.  
  5432.  
  5433.        If there is no error, FormFree() returns NO_ERROR.
  5434.  
  5435.        If there are errors FormFree() returns the following and sets
  5436.        window_error_code to this value:
  5437.  
  5438.        UNDEFINED_FORM if the FORMPTR does not exist.
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.          Page 88        The C Data Forms Library               Page 88     
  5473.  
  5474.                          MISCELLANEOUS FORM FUNCTIONS
  5475.                          ----------------------------
  5476.  
  5477.        FormGetFieldString()
  5478.        --------------------
  5479.  
  5480.        The FormGetFieldString() returns the input entered in the field
  5481.        buffer.  Here is the prototype:
  5482.  
  5483.        int FormGetFieldString(FORMPTR form, int entry, char *buffer)
  5484.  
  5485.        The first two arguments are the FORMPTR and field entry number.
  5486.        The third argument is the pointer to a buffer that the field data
  5487.        will be copied to.  The buffer must be large enough to hold the
  5488.        string plus 1 for the null byte.
  5489.  
  5490.        If there is no error, FormGetFieldString() returns NO_ERROR.
  5491.  
  5492.        If there are errors, FormGetFieldString() returns one of the
  5493.        following and sets window_error_code to one these values:
  5494.  
  5495.        UNDEFINED_FORM if the FORMPTR does not exist.
  5496.        UNDEFINED_FIELD if the field entry does not exist
  5497.  
  5498.  
  5499.        FormGetFieldRowCol()
  5500.        --------------------
  5501.  
  5502.        The FormGetFieldRowCol() function returns the coordinates of a
  5503.        field in a viewport.  This function is useful if you have a virtual
  5504.        form, and want to know where the field is located in the viewport,
  5505.        and not the virtual window.  Here is the prototype:
  5506.  
  5507.        int FormGetFieldRowCol(FORMPTR form, int entry, unsigned *row,
  5508.                                unsigned *col)
  5509.  
  5510.        The *row and *col arguments are pointers to integers that will
  5511.        store the row and column of the field, respectively.
  5512.  
  5513.        Since virtual forms can scroll left, right, up, or down, depending
  5514.        on where the field is, this function can be useful to pinpoint
  5515.        where the field is located in the viewport.  If the form is a
  5516.        simple windowed form, *row and *col will just contain the row and
  5517.        column of the field when initialized.
  5518.  
  5519.        If there is no error, FormGetFieldRowCol() returns NO_ERROR.
  5520.  
  5521.        If there are errors, FormGetFieldRowCol() returns one of the
  5522.        following and sets window_error_code to one these values:
  5523.  
  5524.        UNDEFINED_FORM if the FORMPTR does not exist.
  5525.  
  5526.        UNDEFINED_FIELD if the field entry does not exist
  5527.  
  5528.        FIELD_NOT_IN_VIEW if the field is not currently displayed in the
  5529.        viewport.  If this error occurs, *row and *col are invalid and
  5530.        should not be used.
  5531.  
  5532.          Page 89        The C Data Forms Library               Page 89     
  5533.  
  5534.                                FORM MACROS
  5535.                                -----------
  5536.  
  5537.        Most of these macros use individual FIELD_ENTRY's as an argument.
  5538.        You should use the GET_FIELD_FROM_FORM() macro to get individual
  5539.        field entries from a form.  An example will follow the first two
  5540.        macro definitions to illustrate how to get an individual
  5541.        FIELD_ENTRY.
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.        GET_FIELD_FROM_FORM(form,entry) - returns the FIELD_ENTRY for a
  5548.                                        form.  This macro simplifies
  5549.                                        getting individual FIELD_ENTRY's
  5550.                                        from an array of field entries.
  5551.  
  5552.        FIELD_PROTECT_ON(entry)         - returns 1 if the FIELD_ENTRY
  5553.                                        entry has the FIELD_PROTECT option
  5554.                                        on, 0 otherwise.
  5555.  
  5556.  
  5557.        Example:
  5558.  
  5559.  
  5560.        FIELD_ENTRY fields[] = { /* ... List of field entries ... */};
  5561.  
  5562.                /* other stuff */
  5563.  
  5564.        FORMPTR form;
  5565.  
  5566.        main()
  5567.        {
  5568.        int is_on;
  5569.        FIELD_ENTRY fe;
  5570.  
  5571.        .
  5572.        .
  5573.        .
  5574.  
  5575.        /* Here is one way to get the third FIELD_ENTRY in the
  5576.           fields array */
  5577.  
  5578.        fe = fields[2];  /* Gets the third field entry in array fields */
  5579.        is_on = FIELD_PROTECT_ON(fe);
  5580.  
  5581.        /* Here is another way to get the third field entry, given that the
  5582.        form exists and it was initialized with the fields array */
  5583.  
  5584.        fe = GET_FIELD_FROM_FORM(form,3);
  5585.        is_on = FIELD_PROTECT_ON(fe);
  5586.  
  5587.        }
  5588.  
  5589.  
  5590.  
  5591.  
  5592.          Page 90        The C Data Forms Library               Page 90     
  5593.  
  5594.        Remember when accessing FIELD_ENTRY's directly from the array, the
  5595.        first FIELD_ENTRY is 0, the second is FIELD_ENTRY 1, etc.  However,
  5596.        when using a few of the macros that allow a pointer to a form and
  5597.        an entry number, entries are numbered from 1 to the highest entry.
  5598.  
  5599.  
  5600.        FIELD_COMMA_ON(entry) - returns 1 if the FIELD_ENTRY entry has the
  5601.                                FIELD_COMMA option on, 0 otherwise.
  5602.  
  5603.        FIELD_RJUSTIFY_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5604.                                the FIELD_RJUSTIFY option on, 0 otherwise.
  5605.  
  5606.        FIELD_LJUSTIFY_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5607.                                the FIELD_LJUSTIFY option on, 0 otherwise.
  5608.  
  5609.        FIELD_UPPERCASE_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5610.                                the FIELD_UPPERCASE option on, 0 otherwise.
  5611.  
  5612.        FIELD_LOWERCASE_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5613.                                the FIELD_LOWERCASE option on, 0 otherwise.
  5614.  
  5615.        FIELD_CHECKSPACES_ON(entry) - returns 1 if the FIELD_ENTRY entry
  5616.                                has the FIELD_CHECKSPACES option on, 0
  5617.                                otherwise.
  5618.  
  5619.        FIELD_ENHANCEDKEY_ON(entry) - returns 1 if the FIELD_ENTRY entry
  5620.                                has the FIELD_ENHANCEDKEY option on, 0
  5621.                                otherwise.
  5622.  
  5623.        FIELD_CHECKREGEXP_ON(entry) - returns 1 if the FIELD_ENTRY entry
  5624.                                has the FIELD_CHECKREGEXP option on, 0
  5625.                                otherwise.
  5626.  
  5627.        FIELD_AUTORETURN_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5628.                                the FIELD_AUTORETURN option on, 0
  5629.                                otherwise.
  5630.  
  5631.        FIELD_CHECKREGEXP_IGNORECASE_ON(entry) -  returns 1 if the
  5632.                                                FIELD_ENTRY entry has the
  5633.                                                FIELD_CHECKREGEXP_IGNORECASE option on, 0 otherwise.
  5634.  
  5635.        FIELD_FLUSHBUFFER_ON(entry) - returns 1 if the FIELD_ENTRY entry
  5636.                                has the FIELD_FLUSHBUFFER option on, 0
  5637.                                otherwise.
  5638.  
  5639.        FIELD_HOMECURSOR_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5640.                                the FIELD_HOMECURSOR option on, 0
  5641.                                otherwise.
  5642.  
  5643.        FIELD_ZSUPPRESS1_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5644.                                the FIELD_ZSUPPRESS1 option on, 0
  5645.                                otherwise.
  5646.  
  5647.        FIELD_ZSUPPRESS2_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5648.                                the FIELD_ZSUPPRESS2 option on, 0
  5649.                                otherwise.
  5650.  
  5651.  
  5652.          Page 91        The C Data Forms Library               Page 91     
  5653.  
  5654.        FIELD_PASSWORD_ON(entry) - returns 1 if the FIELD_ENTRY entry has
  5655.                                the FIELD_PASSWORD option on, 0 otherwise.
  5656.  
  5657.  
  5658.        FIELD_OVERRIDE_FORWARD_ON(entry) - returns 1 if the FIELD_ENTRY
  5659.                                        entry has the
  5660.                                        FIELD_OVERRIDE_FORWARD option on, 0
  5661.                                        otherwise.
  5662.  
  5663.        FIELD_OVERRIDE_BACKWARD_ON(entry) - returns 1 if the FIELD_ENTRY
  5664.                                        entry has the
  5665.                                        FIELD_OVERRIDE_BACKWARD option on,
  5666.                                        0 otherwise.
  5667.  
  5668.        FIELD_CLEARFIELD_ON(entry) - returns 1 if the FIELD_ENTRY entry
  5669.                                     will be cleared if the first key
  5670.                                     hit in this field is a key
  5671.                                     recognized by the field's regular
  5672.                                     expression.
  5673.  
  5674.        FORM_DIRECTION(form) -
  5675.                returns FORM_FORWARD if the user is moving the input cursor
  5676.                towards the last field in the form, FORM_BACKWARD if the
  5677.                user is moving the form input cursor toward the first
  5678.                field.  If the FORM_WRAP option is on, FORM_DIRECTION()
  5679.                does not change if the form has wrapped to the first or
  5680.                last available field.
  5681.  
  5682.        This macro is useful if you want to invoke a pre or post-input
  5683.        function only if the user is moving toward the last field and not
  5684.        if they are going toward the first field.
  5685.  
  5686.  
  5687.        FORM_EXPLODE_TYPE(form) - returns what type of special effect will
  5688.                                be used when the form window is displayed
  5689.                                or hidden.  You can also assign values to
  5690.                                this macro.  The default value is NOEFFECT.
  5691.  
  5692.                                Example:  FORM_EXPLODE_TYPE(form) = EXPLODE;
  5693.  
  5694.        FORM_WRAP_ON(form) - returns 1 if the FORM_WRAP option is on, 0
  5695.                             otherwise.
  5696.  
  5697.        FORM_CHECK_ON(form) - returns 1 if the FORM_CHECK option is on, 0
  5698.                              otherwise.
  5699.  
  5700.        FORM_EXIT_INITIAL_ON(form) - returns 1 if the FORM_EXIT_INITIAL
  5701.                                     option is on, 0 otherwise.
  5702.  
  5703.        FORM_HIGHLIGHT_ON(form) - returns 1 if the FORM_HIGHLIGHT option is
  5704.                                  on, 0 otherwise.
  5705.  
  5706.        FORM_VIRTUAL_ON(form) - returns 1 if the form is a virtual form, 0
  5707.                                otherwise.
  5708.  
  5709.        FORM_NOEXIT_LAST_ON(form) - returns 1 if the FORM_NOEXIT_LAST
  5710.                                    option is on, 0 otherwise.
  5711.  
  5712.          Page 92        The C Data Forms Library               Page 92     
  5713.  
  5714.        FORM_STATIC_ON(form) - returns 1 if the FORM_STATIC option is on, 0
  5715.                               otherwise.
  5716.  
  5717.        FORM_WINDOW(form) - returns the pointer (WPOINTER) to the form's
  5718.                            window.
  5719.  
  5720.        FORM_VIRTUAL_WINDOW(form) - returns the pointer (VWPOINTER) to the
  5721.                                    form's virtual window.
  5722.  
  5723.        FORM_NUMBER_OF_FIELDS(form) - returns an integer which is the
  5724.                                      number of fields in a form.
  5725.  
  5726.        FIELD_IN_RANGE(form,entry) - returns 1 if the entry number exists
  5727.                                     in a form, 0 otherwise.
  5728.  
  5729.        FIELD_ROW(entry) - returns an integer which is the row of the
  5730.                           FIELD_ENTRY entry.
  5731.  
  5732.        FIELD_COLUMN(entry) - returns an integer which is the column of the
  5733.                              FIELD_ENTRY entry.
  5734.  
  5735.        FIELD_TYPE(entry) - returns an integer denoting the field type of a
  5736.                            FIELD_ENTRY (i.e.  INTEGER, STRING, etc.)
  5737.  
  5738.        FIELD_MASK(entry) - returns a pointer (char *) to the mask string
  5739.                            used for a FIELD_ENTRY.
  5740.  
  5741.        FIELD_FILL(entry) - returns an integer that denotes the fill
  5742.                            character used for a FIELD_ENTRY.
  5743.  
  5744.        FIELD_MINIMUM(entry) - returns an integer which denotes the minimum
  5745.                               number of characters needed to be filled in
  5746.                               for a FIELD_ENTRY.
  5747.  
  5748.        FIELD_VISIBLE_WIDTH(entry) - returns an integer which is the
  5749.                                     visible width of a FIELD_ENTRY.
  5750.  
  5751.        FIELD_REGEXP(entry) - returns a pointer (char *) to the regular
  5752.                              expression string used in a FIELD_ENTRY
  5753.                              entry.
  5754.  
  5755.        FIELD_ATTRIBUTE(entry) - returns an integer which denotes the
  5756.                                 attribute used for the FIELD_ENTRY entry.
  5757.  
  5758.        FIELD_VARPTR(entry) - returns a pointer (void *) to the user's
  5759.                              variable that will hold the converted data
  5760.                              of the FIELD_ENTRY entry.
  5761.  
  5762.        FIELD_CHANGE(form,entry) - returns 1 if the data entered in the
  5763.                                   field defined by entry has been changed
  5764.                                   since editing the form, 0 otherwise.  If
  5765.                                   the form is re-edited with another call
  5766.                                   to FormGetInput(), FIELD_CHANGE() is
  5767.                                   reset to 0 for all fields in the form.
  5768.  
  5769.  
  5770.  
  5771.  
  5772.          Page 93        The C Data Forms Library               Page 93     
  5773.  
  5774.        FORM_CHANGE(form)        - returns 1 if any fields in the form have
  5775.                                changed, 0 otherwise.  If the form is
  5776.                                re-edited with another call to
  5777.                                FormGetInput(), FORM_CHANGE() returns 0.
  5778.  
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.  
  5822.  
  5823.  
  5824.  
  5825.  
  5826.  
  5827.  
  5828.  
  5829.  
  5830.  
  5831.  
  5832.          Page 94        The C Data Forms Library               Page 94     
  5833.  
  5834.